> ## 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 Ads

> 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.

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](https://ads-api.reddit.com/docs/v3/) for full documentation.

<Warning>This provider requires your own credentials — connect your API key or OAuth account before use.</Warning>

<Info>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](https://ads-api.reddit.com/api/v3). Most resources live under an ad account, e.g. /ad\_accounts/\{ad\_account\_id}/\{campaigns|ad\_groups|ads|custom\_audiences|saved\_audiences|pixels|funding\_instruments|profiles|lead\_gen\_forms|reports}. Discover ad\_account\_ids via GET /me/businesses then GET /businesses/\{business\_id}/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/](https://ads-api.reddit.com/docs/v3/) for full reference. The endpoints below are curated examples.</Info>

## 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://ads-api.reddit.com/api/v3/me/businesses', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fme%2Fbusinesses" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://ads-api.reddit.com/api/v3/businesses/{business_id}/ad_accounts', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fbusinesses%2F%7Bbusiness_id%7D%2Fad_accounts" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/campaigns', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fcampaigns" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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"
    }
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fcampaigns" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"data":{"name":"Q2 Awareness Campaign","objective":"TRAFFIC","funding_instrument_id":"{funding_instrument_id}","configuration_status":"PAUSED"}}'
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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"}} });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X PATCH "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fcampaigns%2F%7Bcampaign_id%7D" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"data":{"configuration_status":"ACTIVE"}}'
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ad_groups', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fad_groups" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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"
          ]
        }
      }
    }
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fad_groups" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"data":{"campaign_id":"{campaign_id}","name":"Programmer audience — US","configuration_status":"PAUSED","bid_strategy":"MAXIMIZE_VOLUME","targeting":{"communities":["t5_2fwo"],"geolocations":{"country_codes":["US"]}}}}'
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/ads', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fads" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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"
    }
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fads" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"data":{"ad_group_id":"{ad_group_id}","post_id":"{post_id}","name":"Programmers — Q2 traffic ad","configuration_status":"PAUSED"}}'
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/custom_audiences', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fcustom_audiences" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/custom_audiences/{custom_audience_id}', { method: 'DELETE' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X DELETE "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fcustom_audiences%2F%7Bcustom_audience_id%7D" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json"
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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"
    }
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fcustom_audiences" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"data":{"name":"Newsletter subscribers — May","type":"CUSTOMER_LIST"}}'
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://ads-api.reddit.com/api/v3/ad_accounts/{ad_account_id}/pixels', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Fpixels" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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..."
        }
      }
    ]
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fconversions%2Fevents%2F%7Bpixel_id%7D" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"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..."}}]}'
    ```
  </Tab>
</Tabs>

### 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

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    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"
    }
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fads-api.reddit.com%2Fapi%2Fv3%2Fad_accounts%2F%7Bad_account_id%7D%2Freports" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"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"}}'
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="All Providers" icon="grid" href="/gateway/supported-providers">
    Browse all supported AI providers
  </Card>

  <Card title="Forward Proxy" icon="route" href="/gateway/forward-proxy">
    Learn how to construct proxy URLs and authenticate requests
  </Card>
</CardGroup>