Skip to main content

Documentation Index

Fetch the complete documentation index at: https://lava.so/docs/llms.txt

Use this file to discover all available pages before exploring further.

Reddit’s official Ads API for managing the full lifecycle of Reddit advertising campaigns — businesses, ad accounts, campaigns, ad groups, ads, audiences, pixels, conversions, and reporting. Best for agents that need to launch, optimize, or report on native Reddit ads (subreddit and conversation placements) on behalf of an authorized advertiser. Unlike aggregator marketing platforms, this is a first-party surface that exposes Reddit-specific targeting (communities, interests, geographies) and granular reporting breakdowns. 15 example endpoints available through Lava’s AI Gateway. See the Reddit Ads API docs for full documentation.
This provider requires your own credentials — connect your API key or OAuth account before use.
This is a catch-all provider — any valid URL under https://ads-api.reddit.com is supported. Reddit Ads API. Base URL: https://ads-api.reddit.com/api/v3. Most resources live under an ad account, e.g. /ad_accounts//. Discover ad_account_ids via GET /me/businesses then GET /businesses//ad_accounts. Ad account IDs are prefixed a2_, business IDs are UUIDs. Pagination is URL-based: follow pagination.next_url directly until null. Reddit aggressively rate-limits requests with default User-Agent strings (curl/, python-requests/, etc.) — always send a descriptive User-Agent in the format {platform}:{app_id}:{version} (by /u/{reddit_username}). See https://ads-api.reddit.com/docs/v3/ for full reference. The endpoints below are curated examples.

​
Endpoints

​
List businesses the authorized user has access to. Returns business ID (UUID), name, industry, country, and creator. Start here to discover business_ids before fetching ad accounts.

GET https://ads-api.reddit.com/api/v3/me/businesses — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/me/businesses', { method: 'GET' });

​
List ad accounts under a business. The bare /ad_accounts endpoint is gated; this is the canonical listing path. Returns ad_account_id (a2_ prefix), currency, time zone, and admin_approval status.

GET https://ads-api.reddit.com/api/v3/businesses/{business_id}/ad_accounts — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/businesses/{business_id}/ad_accounts', { method: 'GET' });

​
List campaigns under an ad account. Paginated; follow pagination.next_url for additional pages. Returns campaign id, name, status (ACTIVE/PAUSED/ARCHIVED), objective, and budget settings.

GET https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/campaigns — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/campaigns', { method: 'GET' });

​
Create a new campaign under an ad account. New campaigns default to PAUSED state; activate by updating configuration_status to ACTIVE.

POST https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/campaigns — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/campaigns', {
  body: {
"data": {
  "name": "Q2 Awareness Campaign",
  "objective": "TRAFFIC",
  "funding_instrument_id": "{funding_instrument_id}",
  "configuration_status": "PAUSED"
}
},
});

​
Update campaign settings. Common updates: configuration_status (PAUSED ↔ ACTIVE), name, budget. Only fields included in data are modified.

PATCH https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id} — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/campaigns/{campaign_id}', { method: 'PATCH', body: {"data":{"configuration_status":"ACTIVE"}} });

​
List ad groups under an ad account. Ad groups define targeting, bidding, schedule, and conversion_pixel_id within a campaign.

GET https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ad_groups — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ad_groups', { method: 'GET' });

​
Create an ad group under a campaign. Required fields include campaign_id, name, bid, targeting (communities, geos, interests), and conversion_pixel_id (required for CBO campaigns from July 13, 2026).

POST https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ad_groups — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ad_groups', {
  body: {
"data": {
  "campaign_id": "{campaign_id}",
  "name": "Programmer audience — US",
  "configuration_status": "PAUSED",
  "bid_strategy": "MAXIMIZE_VOLUME",
  "targeting": {
    "communities": [
      "t5_2fwo"
    ],
    "geolocations": {
      "country_codes": [
        "US"
      ]
    }
  }
}
},
});

​
List ads under an ad account. Each ad references a post (creative) and an ad group, and inherits targeting from the ad group.

GET https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ads — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ads', { method: 'GET' });

​
Create an ad under an ad group. Requires ad_group_id, name, and post_id (the creative — created via the Posts/Structured Posts endpoints).

POST https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ads — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ads', {
  body: {
"data": {
  "ad_group_id": "{ad_group_id}",
  "post_id": "{post_id}",
  "name": "Programmers — Q2 traffic ad",
  "configuration_status": "PAUSED"
}
},
});

​
List custom audiences (CUSTOMER_LIST, WEBSITE, MOBILE_APP, etc.) under an ad account. Use these as targeting building blocks for ad groups.

GET https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/custom_audiences — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/custom_audiences', { method: 'GET' });

​
Delete a custom audience by ID. Removes the audience and any seed identifiers; ad groups still referencing it lose access on their next refresh.

DELETE https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/custom_audiences/{custom_audience_id} — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/custom_audiences/{custom_audience_id}', { method: 'DELETE' });

​
Create a custom audience. CUSTOMER_LIST audiences accept hashed identifiers (EMAIL_SHA256, MAID_SHA256) — pre-hash before upload. Subsequent identifier batches use the Update Custom Audience Users endpoint.

POST https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/custom_audiences — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/custom_audiences', {
  body: {
"data": {
  "name": "Newsletter subscribers — May",
  "type": "CUSTOMER_LIST"
}
},
});

​
List Reddit Pixels for an ad account. Required to find the conversion_pixel_id for ad-group creation and to send conversion events.

GET https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/pixels — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/pixels', { method: 'GET' });

​
Conversions API (CAPI) — post server-side conversion events to a pixel. Path uses the pixel_id from List Pixels. Each event needs event_at (Unix seconds), event_type, and a user identifier (email, hashed; click_id; or device_id).

POST https://ads-api.reddit.com/api/v3/conversions/events/{pixel_id} — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/conversions/events/{pixel_id}', {
  body: {
"test_mode": false,
"events": [
  {
    "event_at": 1715212800,
    "event_type": {
      "tracking_type": "Purchase"
    },
    "event_metadata": {
      "conversion_id": "order_12345",
      "value_decimal": 49.99,
      "currency": "USD"
    },
    "user": {
      "email": "sha256:0123abcd..."
    }
  }
]
},
});

​
Fetch reporting metrics for an ad account. Supply breakdowns (DATE, CAMPAIGN_ID, AD_GROUP_ID, COMMUNITY, COUNTRY, etc.) and fields (impressions, clicks, spend, conversions). Date range via starts_at/ends_at (ISO 8601). Returns paginated rows under data.

POST https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/reports — Free 
const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/reports', {
  body: {
"data": {
  "breakdowns": [
    "DATE",
    "CAMPAIGN_ID"
  ],
  "fields": [
    "impressions",
    "clicks",
    "spend",
    "cpc",
    "ctr"
  ],
  "starts_at": "2026-05-01T00:00:00Z",
  "ends_at": "2026-05-11T00:00:00Z",
  "time_zone_id": "America/New_York"
}
},
});

​
Next Steps

All Providers

Browse all supported AI providers

Forward Proxy

Learn how to construct proxy URLs and authenticate requests