API Quickstart

The Bronco API lets your own tools, or a measurement partner, pull spend, delivery, and conversion data without a user login. This guide takes you from creating a key to your first report.

The same keys can keep an audience up to date from your CRM or customer data platform, upload customer lists, and create lookalikes. That is covered in Syncing audiences.

1. Create an API key

Only Admins can create keys.

1. In Bronco, go to Settings → API Keys and click Create Key.
2. Enter a Name that says who or what will use the key, such as a partner or an internal tool.
3. Optionally choose Advertisers to limit the key. Leave it empty to include every advertiser, including ones added later.
4. Under Permissions, choose what the key can do. Reporting is ticked already and is all this guide needs. Audiences lets the key create and upload audiences, make lookalikes, and add or remove the people in them.
5. Click Create Key, then copy the key and store it somewhere safe, like a password manager.

The key is shown once. If it's lost, revoke it and create a new one.

Use one key per partner or tool, so you can revoke one without affecting the others.

2. Check the key

Every request goes to https://agentapi-prod-eastus-1.bronco.run/api/v2 with the key as a bearer token.

export BRONCO_API_KEY="brk_live_..."

curl https://agentapi-prod-eastus-1.bronco.run/api/v2/api-keys/current \
  -H "Authorization: Bearer $BRONCO_API_KEY"

A working key returns the account it belongs to, what it can do, the advertisers it's limited to (null means all), and the advertisers it can use right now, by name:

{
  "name": "Reporting dashboard",
  "tenantId": 1024,
  "scopes": ["reports:read"],
  "advertiserIds": null,
  "advertisers": [
    { "id": 42, "name": "Acme Outdoors" },
    { "id": 57, "name": "Acme Kids" }
  ]
}

3. Run a report

A report groups your data by the dimensions you ask for and returns the metrics you choose, for a date range.

curl https://agentapi-prod-eastus-1.bronco.run/api/v2/reports/query \
  -H "Authorization: Bearer $BRONCO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": ["date", "campaign"],
    "metrics": ["spend", "impressions", "purchases", "revenue", "roas"],
    "dateRangePreset": "last7Days"
  }'

{
  "columns": [
    { "key": "date", "label": "Date", "kind": "dimension" },
    { "key": "campaign", "label": "Campaign Name", "kind": "dimension" },
    { "key": "spend", "label": "Spend", "kind": "metric" }
  ],
  "rows": [
    { "date": "2026-09-05", "campaign": "Fall Launch", "spend": 412.5 }
  ],
  "rowCount": 1,
  "truncated": false,
  "rowLimit": 10000,
  "range": { "startDate": "2026-09-05", "endDate": "2026-09-11" },
  "generatedAt": "2026-09-12T14:03:27.000Z"
}

(The response above is shortened to three columns.)

Dimensions

Choose one to four: date, advertiser, campaign, strategy, creative, publisher.

Set "includeIds": true to add an id column next to each advertiser, campaign, strategy, and creative name. Rows are then grouped by id, so two items that share a name stay separate.

Metrics

Choose at least one.

Metric	What it is
spend	What the advertiser is billed.
impressions	Ads delivered.
cpm	Spend per thousand impressions.
pageViews	Page views attributed to your CTV ads.
purchases	Purchases attributed to your CTV ads.
leads	Leads attributed to your CTV ads.
revenue	Revenue from attributed purchases.
cpa	Spend divided by purchases.
costPerLead	Spend divided by leads.
roas	Revenue divided by spend.

A ratio is 0 when its denominator is zero.

Dates

Send either dateRangePreset, or both startDate and endDate as YYYY-MM-DD (the end date is included).

Presets: today, yesterday, thisWeek, lastWeek, last7Days, last30Days, thisMonth, allTime. Weeks start on Monday, and last7Days and last30Days include today.

Reporting days are calendar days in Eastern time (America/New_York). The optional ianaTimeZone only decides what "today" means when a preset is resolved.

Limiting to advertisers

Send "advertiserIds": [42, 57] to include only those advertisers. A key that's limited to certain advertisers can't ask for others.

4. Download a CSV

The same request body sent to /reports/query/export.csv returns a CSV file. Add an optional name to set the file name.

curl https://agentapi-prod-eastus-1.bronco.run/api/v2/reports/query/export.csv \
  -H "Authorization: Bearer $BRONCO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly CTV",
    "dimensions": ["date", "campaign"],
    "metrics": ["spend", "impressions"],
    "dateRangePreset": "lastWeek"
  }' \
  -o weekly-ctv.csv

Large results

One call returns up to 10,000 rows. When more rows matched, truncated is true (or the X-Report-Truncated header is 1 for a CSV). Narrow the date range or use fewer dimensions, and make several calls if you need the full set.

Next steps

• Syncing audiences covers creating an audience and keeping it up to date.
• Authentication, limits, and errors covers key handling, rate limits, the sandbox, and error responses.
• The API reference lists every field and lets you try requests in the browser.