Cost breakdown export

Export account cost data by dimension (products, APIs, datasets, Web Scraper APIs). Same source as Cost Explorer. JSON or CSV per-day, 200 OK on success.

POST /costs/export/json

cURL

cURL

curl --request POST \
  --url https://api.brightdata.com/costs/export/json \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dimension": "web_apis",
  "filters": {},
  "from": "2026-04-01",
  "to": "2026-05-01"
}
'

import requests

url = "https://api.brightdata.com/costs/export/json"

payload = {
    "dimension": "web_apis",
    "filters": {},
    "from": "2026-04-01",
    "to": "2026-05-01"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({dimension: 'web_apis', filters: {}, from: '2026-04-01', to: '2026-05-01'})
};

fetch('https://api.brightdata.com/costs/export/json', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.brightdata.com/costs/export/json",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'dimension' => 'web_apis',
    'filters' => [
        
    ],
    'from' => '2026-04-01',
    'to' => '2026-05-01'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.brightdata.com/costs/export/json"

	payload := strings.NewReader("{\n  \"dimension\": \"web_apis\",\n  \"filters\": {},\n  \"from\": \"2026-04-01\",\n  \"to\": \"2026-05-01\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.brightdata.com/costs/export/json")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"dimension\": \"web_apis\",\n  \"filters\": {},\n  \"from\": \"2026-04-01\",\n  \"to\": \"2026-05-01\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.brightdata.com/costs/export/json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"dimension\": \"web_apis\",\n  \"filters\": {},\n  \"from\": \"2026-04-01\",\n  \"to\": \"2026-05-01\"\n}"

response = http.request(request)
puts response.read_body

200

{
  "2026-04-01": {
    "gd_l1viktl72bvl7bjuj0": 45.2,
    "gd_l1vikfnt1wgvvqz95w": 12.8
  },
  "2026-04-02": {
    "gd_l1viktl72bvl7bjuj0": 38.1
  }
}

This endpoint exports the same per-day, per-resource cost breakdown that the Control Panel’s Cost Explorer displays, in JSON or CSV, grouped by the dimension you pick (products, zones, datasets, Web Scraper APIs, collectors, domains, dataset snapshots, or WSA snapshots).

The to parameter is exclusive. The day specified in to is not included in the result. To match a calendar month shown in the Control Panel or on your invoice, set to to the first day of the following month. For example, from=2026-04-01&to=2026-05-01 returns all of April 2026.

Paste your API key into the authorization field. To get an API key, create an account and learn how to generate an API key.

When to use this endpoint

Use this endpoint when you need cost data that GET /zone/cost cannot return. The /zone/cost endpoint is scoped to a single zone, which means it cannot break down Web Scraper API costs (those are keyed by dataset_id, not by zone name) and it cannot answer questions like “What did I spend on datacenter and unlocker proxies combined last month?”.

This endpoint accepts a dimension parameter that groups costs by the same buckets the Control Panel Cost Explorer uses.

Dimension	Groups costs by
products	Product family (datacenter, residential, ISP, mobile, unlocker, SERP API, Browser API, and so on)
types	Network or charge type
zones	Individual zones in your account
datasets	Dataset Marketplace dataset purchases
web_apis	Web Scraper API dataset_ids
collectors	Scraper Studio collectors
domains	Target domains
ws_api_snaps	Web Scraper API snapshots
snapshots	Dataset snapshots

The dimensions match what you see in the Cost Explorer UI, so the simplest way to discover what each dimension returns is to open Cost Explorer in the Control Panel and switch the grouping.

Reproduce your monthly invoice for a dimension

To retrieve the full monthly cost broken down by Web Scraper API datasets for April 2026:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimension": "web_apis",
    "filters": {},
    "from": "2026-04-01",
    "to": "2026-05-01"
  }' \
  "https://api.brightdata.com/costs/export/json"

Response shape (one entry per day; each day maps resource ID to billed USD):

{
  "2026-04-01": {
    "gd_l1viktl72bvl7bjuj0": 45.20,
    "gd_l1vikfnt1wgvvqz95w": 12.80
  },
  "2026-04-02": {
    "gd_l1viktl72bvl7bjuj0": 38.10
  }
}

For the same data as CSV, call POST /costs/export/csv with the identical request body. The CSV pivots the response into one row per day with one column per resource ID that appears in the date range, so column count varies with the data:

Day,gd_l1viktl72bvl7bjuj0,gd_l1vikfnt1wgvvqz95w
2026-04-01,45.20,12.80
2026-04-02,38.10,0

Using the filters field

The filters object uses Bright Data’s internal charges-structure notation, the same notation used by Cost Explorer. Building a filter from scratch requires knowledge of that structure. Most callers leave filters empty ({}) and rely on the dimension parameter to scope the response.

One working example, restricting the result to datacenter and Web Unlocker products:

{
  "props": {
    "product": {
      "whitelist": ["dc", "unblocker"]
    }
  }
}

If you need a filter that the dimension alone cannot express, contact Bright Data support with the question you are trying to answer. We do not currently publish a complete filter grammar; support can build the filter you need or confirm that no filter is required.

Rate limits

• 1,000 requests per minute
• 5,000 requests per hour

The endpoint accepts any API key with cost-data access. There is no separate billing-admin scope.

Reconciling with raw request logs

The values returned by this endpoint are the source of truth for billing. They match the Control Panel’s Cost Explorer and Usage Overview, and they roll up into your invoice. If you compare these values against raw request logs you collect yourself (for example, access logs forwarded to Logz or CloudWatch), expect differences of a few percent. Raw logs may capture requests that were never committed to the billing database because of async aggregation timing or transient network issues. Your invoice always reflects the values returned by this endpoint.

Related endpoints

• Total cost & bandwidth for a zone. Single-zone cost and bandwidth over a date range. Cannot return Web Scraper API or Scraper Studio cost.
• Bandwidth stats for a zone. Bandwidth only, no cost.
• Bandwidth stats for all your Zones. Aggregate bandwidth across zones.

Authorizations

Authorization · string · header · required

Use your Bright Data API Key as a Bearer token in the Authorization header.

How to authenticate:

1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users
2. Include the API Key in the Authorization header of your requests
3. Format: Authorization: Bearer YOUR_API_KEY

Example:

Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

Learn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication

Body

application/json

dimension · enum<string> · required

The dimension to group costs by. Same dimension semantics as the Control Panel Cost Explorer.

Available options: products, types, zones, datasets, web_apis, collectors, domains, ws_api_snaps, snapshots

from · string<date> · required

Inclusive start date in YYYY-MM-DD format. UTC.

to · string<date> · required

Exclusive end date in YYYY-MM-DD format. UTC. The day specified is NOT included in the result. To match a calendar month, set to to the first day of the following month (e.g., from=2026-04-01&to=2026-05-01 returns all of April 2026).

filters · object

Optional filter object. Uses Bright Data's internal charges-structure notation and requires knowledge of that structure to construct. Contact Bright Data support if you need help building a filter.

Example: { "props": { "product": { "whitelist": ["dc", "unblocker"] } } }

Response

200 - application/json

Cost breakdown grouped by day, then by resource ID. The resource ID format depends on the requested dimension (e.g., for dimension=web_apis, resource IDs are dataset IDs like gd_l1viktl72bvl7bjuj0). Amounts are billed USD for the day.

{key} · object

Show child attributes