API Reference
Campaigns
Campaign performance, ROAS, ad-level breakdowns, and daily spend trends.
Campaigns
Top Campaigns
GET /api/v1/campaignsReturns top-performing campaigns ranked by attributed outcome value, with ROAS
and spend data. Pass level to drill down to ad sets or individual ads.
Scope: campaigns:read
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from | string | Yes | Start date in YYYY-MM-DD format. |
date_to | string | Yes | End date in YYYY-MM-DD format. |
model | string | No | Attribution model. Default last_touch. Options: first_touch, linear, position_based, time_decay, last_non_direct. |
limit | number | No | Maximum results. Default 10, max 100. |
level | string | No | Hierarchy level: campaign, ad_set, or ad. When set, returns detailed performance fields. |
Request
curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
"https://www.atribu.app/api/v1/campaigns?date_from=2026-03-01&date_to=2026-03-25&model=last_touch&limit=5"const res = await fetch(
"https://www.atribu.app/api/v1/campaigns?date_from=2026-03-01&date_to=2026-03-25&model=last_touch&limit=5",
{ headers: { Authorization: "Bearer atb_live_YOUR_KEY" } }
);
const { data, meta } = await res.json();import requests
res = requests.get(
"https://www.atribu.app/api/v1/campaigns",
headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
params={
"date_from": "2026-03-01",
"date_to": "2026-03-25",
"model": "last_touch",
"limit": 5,
},
)
data = res.json()["data"]Response
{
"data": [
{
"campaign_id": "uuid",
"campaign_name": "Spring Sale - Conversions",
"spend": 1800.00,
"outcome_count": 45,
"outcome_value": 6200.00,
"roas": 3.44
}
],
"meta": {
"date_from": "2026-03-01",
"date_to": "2026-03-25",
"profile_id": "uuid"
}
}Response fields
| Field | Type | Description |
|---|---|---|
campaign_id | string | Internal campaign UUID. |
campaign_name | string | Human-readable campaign name from the ad platform. |
spend | number | Total ad spend in your reporting currency. |
outcome_count | number | Number of attributed conversions. |
outcome_value | number | Total attributed cash revenue. |
roas | number | Return on ad spend (outcome_value / spend). |
Ad-level detail
Pass level=ad to get granular performance per ad creative. This adds
additional fields to each row.
curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
"https://www.atribu.app/api/v1/campaigns?date_from=2026-03-01&date_to=2026-03-25&level=ad"const res = await fetch(
"https://www.atribu.app/api/v1/campaigns?date_from=2026-03-01&date_to=2026-03-25&level=ad",
{ headers: { Authorization: "Bearer atb_live_YOUR_KEY" } }
);
const { data } = await res.json();res = requests.get(
"https://www.atribu.app/api/v1/campaigns",
headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
params={"date_from": "2026-03-01", "date_to": "2026-03-25", "level": "ad"},
)
data = res.json()["data"]Additional fields when level is set
| Field | Type | Description |
|---|---|---|
entity_level | string | The level of this row (campaign, ad_set, ad). |
parent_name | string | Name of the parent entity (campaign or ad set). |
impressions | number | Total impressions served. |
clicks | number | Total clicks. |
reach | number | Unique accounts reached. |
ctr | number | Click-through rate (%). |
avg_cpm | number | Average cost per 1,000 impressions. |
avg_cpc | number | Average cost per click. |
cac | number | Customer acquisition cost (spend / outcome_count). |
status | string | Entity status (ACTIVE, PAUSED, etc.). |
objective | string | Campaign objective. |
daily_budget | number | Daily budget if set on the platform. |
Campaign Trend
GET /api/v1/campaigns/trendReturns daily spend, impressions, and clicks for up to 10 specific campaigns, ad sets, or ads. Use this to render sparklines or compare entity performance over time.
Scope: campaigns:read
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from | string | Yes | Start date in YYYY-MM-DD format. |
date_to | string | Yes | End date in YYYY-MM-DD format. |
entity_ids | string | Yes | Comma-separated list of entity UUIDs (max 10). |
level | string | No | campaign, ad_set, or ad. Default campaign. |
Request
curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
"https://www.atribu.app/api/v1/campaigns/trend?date_from=2026-03-20&date_to=2026-03-25&entity_ids=uuid1,uuid2&level=campaign"const ids = ["uuid1", "uuid2"].join(",");
const res = await fetch(
`https://www.atribu.app/api/v1/campaigns/trend?date_from=2026-03-20&date_to=2026-03-25&entity_ids=${ids}&level=campaign`,
{ headers: { Authorization: "Bearer atb_live_YOUR_KEY" } }
);
const { data } = await res.json();import requests
res = requests.get(
"https://www.atribu.app/api/v1/campaigns/trend",
headers={"Authorization": "Bearer atb_live_YOUR_KEY"},
params={
"date_from": "2026-03-20",
"date_to": "2026-03-25",
"entity_ids": "uuid1,uuid2",
"level": "campaign",
},
)
data = res.json()["data"]Response
{
"data": [
{ "entity_id": "uuid1", "date": "2026-03-20", "spend": 120.00, "impressions": 15000, "clicks": 340 },
{ "entity_id": "uuid1", "date": "2026-03-21", "spend": 135.00, "impressions": 16200, "clicks": 380 },
{ "entity_id": "uuid2", "date": "2026-03-20", "spend": 95.00, "impressions": 11800, "clicks": 275 }
],
"meta": {
"date_from": "2026-03-20",
"date_to": "2026-03-25",
"profile_id": "uuid"
}
}Response fields
| Field | Type | Description |
|---|---|---|
entity_id | string | The campaign, ad set, or ad UUID. |
date | string | Calendar date (YYYY-MM-DD). |
spend | number | Ad spend for that entity on that day. |
impressions | number | Impressions served. |
clicks | number | Clicks recorded. |
Entity ID format
entity_ids expects Atribu internal UUIDs (from the campaign_id field in
the Top Campaigns response), not platform-specific IDs. You can pass up to
10 IDs in a single request.