REST API

AdFire REST API

Integrate your ad data into any tool, script, or dashboard. One API key, full access to your Meta and Google Ads data.

Base URLhttps://app.adfire.io/api/v1

Authentication

All requests require an API key passed as a Bearer token in the Authorization header. Generate a key at /dashboard/settings.

Authorization: Bearer af_sk_...

Status codes

200Success — JSON response body.

401Missing or invalid API key.

429Rate limited — back off and retry.

500Internal server error — contact support.

Endpoints

All endpoints are authenticated. Parameters marked with * are required. For live interactive testing, use the API Explorer.

GET

/api/v1/ad-accounts

List all connected Meta & Google ad accounts with sync status.

Parameters

Name	Type	Description
provider	enum	Filter by platform.(meta, google)

Example response shape

{
  "ad_accounts": [
    {
      "id": "string",
      "name": "string",
      "provider": "meta | google",
      "externalId": "string",
      "currency": "string",
      "status": "string",
      "lastEntitySyncAt": "ISO8601 | null",
      "lastInsightsSyncAt": "ISO8601 | null"
    }
  ]
}

GET

/api/v1/campaigns

List campaigns with performance metrics.

Parameters

Name	Type	Description
ad_account_id	string	Filter by ad account.
period	enum	Metrics window.(1d, 7d, 14d, 30d, 90d, lifetime)
status	enum	Campaign status filter.(ACTIVE, PAUSED, DELETED)
limit	number	Max results (up to 200).
sort_by	enum	Sort field.(spend, roas, ctr, cpc, impressions, clicks)
sort_order	enum	Sort direction.(desc, asc)
roas_min	number	Minimum ROAS filter (inclusive).
roas_max	number	Maximum ROAS filter (inclusive).

Example response shape

{
  "campaigns": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "objective": "string",
      "provider": "meta | google",
      "metrics": {
        "spend": 1234.56,
        "roas": 3.2,
        "conversions": 42,
        "impressions": 100000,
        "clicks": 1500,
        "ctr": 1.5,
        "cpc": 0.82
      }
    }
  ]
}

GET

/api/v1/campaigns/{id}

Get detailed campaign metrics for a single campaign.

Parameters

Name	Type	Description
period	enum	Metrics window.(1d, 7d, 14d, 30d, 90d, lifetime)

Example response shape

{
  "id": "string",
  "name": "string",
  "status": "string",
  "objective": "string",
  "bidStrategy": "string",
  "dailyBudget": 50.00,
  "provider": "meta | google",
  "metrics": { "spend": 1234.56, "roas": 3.2, ... }
}

GET

/api/v1/adsets

List ad sets (Meta) or ad groups (Google) with metrics.

Parameters

Name	Type	Description
ad_account_id	string	Filter by ad account.
campaign_id	string	Filter by campaign.
period	enum	Metrics window.(1d, 7d, 14d, 30d, 90d, lifetime)
status	enum	Status filter.(ACTIVE, PAUSED, DELETED)
limit	number	Max results (up to 200).
sort_by	enum	Sort field.(spend, roas, ctr, cpc, impressions, clicks)
sort_order	enum	Sort direction.(desc, asc)

Example response shape

{
  "adsets": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "campaignId": "string",
      "dailyBudget": 25.00,
      "metrics": { "spend": 456.78, "roas": 2.8, ... }
    }
  ]
}

GET

/api/v1/adsets/{id}

Get details for a single ad set or ad group.

Parameters

Name	Type	Description
period	enum	Metrics window.(1d, 7d, 14d, 30d, 90d, lifetime)

Example response shape

{
  "id": "string",
  "name": "string",
  "status": "string",
  "bidAmount": 1.50,
  "metrics": { "spend": 456.78, "roas": 2.8, ... }
}

GET

/api/v1/adsets/{id}/targeting

Get parsed targeting spec. Meta: age, gender, geo, interests, audiences, placements, Advantage+. Google: keywords, locations, devices, languages, audiences.

Example response shape

{
  "adsetId": "string",
  "provider": "meta | google",
  "targeting": {
    "ageMin": 25,
    "ageMax": 55,
    "genders": ["male", "female"],
    "geoLocations": [{ "country": "US" }],
    "interests": [{ "id": "...", "name": "..." }],
    "placements": ["facebook_feed", "instagram_feed"]
  }
}

GET

/api/v1/keywords

Google keywords — search across all ad groups. Includes match type, quality score, bid, and 30d performance metrics.

Parameters

Name	Type	Description
adset_id	string	Filter by ad set (Google ad group).
text	string	Search keyword text.
status	enum	Keyword status.(enabled, paused, removed)
match_type	enum	Match type.(EXACT, PHRASE, BROAD)
sort_by	enum	Sort field.(spend, text, quality_score)
limit	number	Max results (up to 500, default 100).

Example response shape

{
  "keywords": [
    {
      "id": "string",
      "text": "running shoes",
      "matchType": "EXACT",
      "status": "enabled",
      "qualityScore": 8,
      "cpcBidMicros": 1500000,
      "metrics": { "impressions": 5000, "clicks": 200, "ctr": 4.0, "cpc": 1.20 }
    }
  ]
}

GET

/api/v1/ads

List individual ads with metrics.

Parameters

Name	Type	Description
ad_account_id	string	Filter by ad account.
campaign_id	string	Filter by campaign.
period	enum	Metrics window.(1d, 7d, 14d, 30d, 90d, lifetime)
status	enum	Status filter.(ACTIVE, PAUSED, DELETED)
limit	number	Max results (up to 200).
sort_by	enum	Sort field.(spend, roas, ctr, cpc, impressions, clicks)
sort_order	enum	Sort direction.(desc, asc)

Example response shape

{
  "ads": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "adsetId": "string",
      "campaignId": "string",
      "thumbnailUrl": "string | null",
      "metrics": { "spend": 123.45, "roas": 4.1, ... }
    }
  ]
}

GET

/api/v1/ads/{id}

Get full ad details including creative analysis.

Parameters

Name	Type	Description
period	enum	Metrics window.(1d, 7d, 14d, 30d, 90d, lifetime)

Example response shape

{
  "id": "string",
  "name": "string",
  "status": "string",
  "metrics": { "spend": 123.45, "roas": 4.1, ... },
  "creativeAnalysis": {
    "overallScore": 82,
    "ctaPresent": true,
    "textDensity": "low",
    "emotionalTone": "inspiring",
    "mobileScore": 90
  }
}

GET

/api/v1/ads/{id}/assets

Get all creative assets for an ad — images, videos, carousel cards with durable API URLs (never expiring CDN links).

Example response shape

{
  "adId": "string",
  "assets": [
    {
      "type": "image | video | carousel_card",
      "url": "/api/assets/...",
      "storageType": "s3 | url",
      "width": 1080,
      "height": 1080
    }
  ]
}

GET

/api/v1/overview

Account-level performance overview across all campaigns.

Parameters

Name	Type	Description
ad_account_id	string	Filter by ad account.
period	enum	Metrics window.(1d, 7d, 14d, 30d, 90d, lifetime)

Example response shape

{
  "period": "30d",
  "totalSpend": 12345.67,
  "totalConversions": 420,
  "blendedRoas": 3.1,
  "activeCampaigns": 12,
  "topCampaigns": [ ... ],
  "platformBreakdown": { "meta": {...}, "google": {...} }
}

GET

/api/v1/recommendations

AI-generated recommendations ranked by priority and estimated revenue impact.

Parameters

Name	Type	Description
ad_account_id	string	Filter by ad account.
category	string	Filter by category (creative, budget, targeting, performance).
limit	number	Max results (default 10).

Example response shape

{
  "recommendations": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "category": "creative | budget | targeting | performance",
      "priority": "CRITICAL | HIGH | MEDIUM | LOW",
      "estimatedImpactUsd": 450.00,
      "status": "pending | implemented | snoozed | dismissed"
    }
  ]
}

GET

/api/v1/search

Full-text search across campaigns, ad sets, and ads.

Parameters

Name	Type	Description
q*	string	Search query.
entity_type	enum	Limit to entity type.(campaign, adset, ad)
limit	number	Max results.

Example response shape

{
  "results": [
    {
      "entityType": "campaign | adset | ad",
      "id": "string",
      "name": "string",
      "status": "string",
      "adAccountId": "string"
    }
  ]
}

GET

/api/v1/time-breakdown

Performance by hour-of-day, day-of-week, or calendar day. Returns spend, impressions, clicks, conversions, and ROAS per bucket. Calls the Meta Insights API live — Meta accounts only.

Parameters

Name	Type	Description
ad_account_id*	string	AdFire ad account ID.
dimension*	enum	Breakdown dimension.(hour_of_day, day_of_week, day)
level	enum	Aggregation level (default: account).(account, campaign, adset, ad)
preset	enum	Date preset (default: 30d).(7d, 14d, 30d, 90d, 6m)
since	string	Start date YYYY-MM-DD (overrides preset).
until	string	End date YYYY-MM-DD (default: yesterday).

Example response shape

{
  "dimension": "hour_of_day",
  "data": [
    {
      "hour": 14,
      "spend": 45.20,
      "impressions": 12000,
      "clicks": 180,
      "conversions": 8,
      "roas": 3.4
    }
  ]
}

GET

/api/v1/analytics

Aggregated analytics. campaigns_by_roas ranks campaigns by ROAS with optional min/max filters. time_breakdown aggregates stored daily data by day-of-week.

Parameters

Name	Type	Description
ad_account_id*	string	AdFire ad account ID.
metric	enum	Analysis type (default: campaigns_by_roas).(campaigns_by_roas, time_breakdown)
roas_min	number	Minimum ROAS filter (campaigns_by_roas).
roas_max	number	Maximum ROAS filter (campaigns_by_roas).
dimension	enum	Breakdown dimension for time_breakdown.(hour_of_day, day_of_week)
period	enum	Metrics window (default: 30d).(7d, 14d, 30d, 90d)
limit	number	Max campaigns returned (default 100).

Example response shape

// metric=campaigns_by_roas
{
  "metric": "campaigns_by_roas",
  "period": "30d",
  "filters": { "roas_min": 2.0, "roas_max": null },
  "count": 8,
  "campaigns": [
    {
      "id": "string",
      "name": "string",
      "status": "ACTIVE",
      "metrics": { "spend": 1234.56, "roas": 5.1, "conversions": 42, ... }
    }
  ]
}

// metric=time_breakdown&dimension=day_of_week
{
  "metric": "time_breakdown",
  "dimension": "day_of_week",
  "data": [
    {
      "day": 1,
      "day_name": "Monday",
      "spend": 890.40,
      "conversions": 38,
      "roas": 3.8,
      "ctr": 2.1,
      "days_sampled": 4
    }
  ]
}

Code examples

Replace af_sk_YOUR_KEY with your actual API key from Settings.

bash — curl

curl -H "Authorization: Bearer af_sk_YOUR_KEY" \
  "https://app.adfire.io/api/v1/campaigns?period=30d&sort_by=roas&sort_order=desc"

javascript — fetch

const res = await fetch(
  "https://app.adfire.io/api/v1/campaigns?period=30d&roas_min=2",
  {
    headers: {
      "Authorization": "Bearer af_sk_YOUR_KEY"
    }
  }
);
const { campaigns } = await res.json();
console.log(campaigns[0].metrics.roas);

python — requests

import requests

headers = {"Authorization": "Bearer af_sk_YOUR_KEY"}

# Get top campaigns by ROAS
resp = requests.get(
    "https://app.adfire.io/api/v1/campaigns",
    params={"period": "30d", "sort_by": "roas", "sort_order": "desc", "limit": 10},
    headers=headers,
)
data = resp.json()
for c in data["campaigns"]:
    print(c["name"], c["metrics"]["roas"])

Try the API live

The interactive API Explorer lets you send real requests, inspect responses, and build your integration without writing any code.

Open API Explorer →