Reddit Ads API

openapi: 3.1.0
info:
  title: Reddit Ads API
  description: >-
    The Reddit Ads API allows advertisers and their partners to
    programmatically create, edit, and manage advertising campaigns and
    audiences on the Reddit platform. It provides endpoints for managing
    ad accounts, campaigns, ad groups, ads, creatives, targeting, custom
    audiences, conversion pixels, and reporting. Authentication is handled
    via OAuth 2.0, and rate limits are set at one request per second.
  version: '3'
  contact:
    name: Reddit Ads Support
    url: https://business.reddithelp.com/s/article/Reddit-Ads-API
  termsOfService: https://business.reddithelp.com/s/article/Reddit-Ads-API-Terms
externalDocs:
  description: Reddit Ads API Documentation
  url: https://ads-api.reddit.com/docs/
servers:
  - url: https://ads-api.reddit.com/api/v3
    description: Reddit Ads API v3 Production Server
tags:
  - name: Accounts
    description: >-
      Endpoints for managing Reddit Ads accounts, including retrieving
      account details and configuration settings.
  - name: Ad Groups
    description: >-
      Endpoints for managing ad groups within campaigns, including
      targeting, bidding, and scheduling configuration.
  - name: Ads
    description: >-
      Endpoints for creating and managing individual ads and their
      associated creative content.
  - name: Campaigns
    description: >-
      Endpoints for creating, reading, updating, and deleting advertising
      campaigns, including budget and schedule management.
  - name: Conversions
    description: >-
      Endpoints for managing conversion pixels and sending server-side
      conversion events via the Conversions API (CAPI).
  - name: Custom Audiences
    description: >-
      Endpoints for managing custom audiences for targeting, including
      email lists, mobile device IDs, and website visitor audiences.
  - name: Funding
    description: >-
      Endpoints for managing account funding instruments and billing
      information.
  - name: Reporting
    description: >-
      Endpoints for retrieving campaign, ad group, and ad performance
      reporting data including impressions, clicks, and conversions.
  - name: Targeting
    description: >-
      Endpoints for retrieving available targeting options including
      interests, communities, locations, and devices.
security:
  - oauth2: []
paths:
  /accounts/{account_id}:
    get:
      operationId: getAccount
      summary: Get Account Details
      description: >-
        Fetches detailed information about a specific Reddit Ads account
        including attribution settings, status, and account configuration.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Account details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Authentication required
        '404':
          description: Account not found
  /accounts/{account_id}/campaigns:
    get:
      operationId: listCampaigns
      summary: List Campaigns
      description: >-
        Lists all campaigns in a Reddit Ads account with filtering,
        pagination, and sorting. Returns campaign IDs, names, status,
        objectives, budgets, and schedule information.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/cursor'
        - name: status
          in: query
          description: >-
            Filter campaigns by status.
          schema:
            type: string
            enum:
              - ACTIVE
              - PAUSED
              - COMPLETED
              - DRAFT
      responses:
        '200':
          description: List of campaigns
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
                  cursor:
                    type: string
                    description: >-
                      Pagination cursor for the next page of results.
        '401':
          description: Authentication required
    post:
      operationId: createCampaign
      summary: Create a Campaign
      description: >-
        Creates a new advertising campaign in the specified Reddit Ads
        account.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignInput'
      responses:
        '201':
          description: Campaign created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '400':
          description: Invalid campaign data
        '401':
          description: Authentication required
  /accounts/{account_id}/campaigns/{campaign_id}:
    get:
      operationId: getCampaign
      summary: Get a Campaign
      description: >-
        Fetches detailed information about a specific Reddit Ads campaign
        including status, budget, schedule, and targeting configuration.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '200':
          description: Campaign details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '404':
          description: Campaign not found
    put:
      operationId: updateCampaign
      summary: Update a Campaign
      description: >-
        Updates an existing campaign's configuration, including name,
        budget, schedule, and status.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/campaignId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignInput'
      responses:
        '200':
          description: Campaign updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '400':
          description: Invalid campaign data
        '404':
          description: Campaign not found
    delete:
      operationId: deleteCampaign
      summary: Delete a Campaign
      description: >-
        Deletes an advertising campaign. The campaign must be in a
        non-active state to be deleted.
      tags:
        - Campaigns
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/campaignId'
      responses:
        '204':
          description: Campaign deleted successfully
        '404':
          description: Campaign not found
  /accounts/{account_id}/ad_groups:
    get:
      operationId: listAdGroups
      summary: List Ad Groups
      description: >-
        Lists ad groups in a Reddit Ads account or campaign, with ad
        groups containing targeting settings and grouping related ads.
      tags:
        - Ad Groups
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/cursor'
        - name: campaign_id
          in: query
          description: >-
            Filter ad groups by campaign ID.
          schema:
            type: string
      responses:
        '200':
          description: List of ad groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdGroup'
                  cursor:
                    type: string
                    description: >-
                      Pagination cursor for the next page.
        '401':
          description: Authentication required
    post:
      operationId: createAdGroup
      summary: Create an Ad Group
      description: >-
        Creates a new ad group within a campaign with targeting and
        bidding configuration.
      tags:
        - Ad Groups
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdGroupInput'
      responses:
        '201':
          description: Ad group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdGroup'
        '400':
          description: Invalid ad group data
  /accounts/{account_id}/ad_groups/{ad_group_id}:
    get:
      operationId: getAdGroup
      summary: Get an Ad Group
      description: >-
        Fetches detailed information about a specific ad group including
        targeting settings, bid configuration, and schedule.
      tags:
        - Ad Groups
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/adGroupId'
      responses:
        '200':
          description: Ad group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdGroup'
        '404':
          description: Ad group not found
    put:
      operationId: updateAdGroup
      summary: Update an Ad Group
      description: >-
        Updates an existing ad group's configuration, including targeting,
        bidding, and scheduling.
      tags:
        - Ad Groups
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/adGroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdGroupInput'
      responses:
        '200':
          description: Ad group updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdGroup'
        '400':
          description: Invalid ad group data
    delete:
      operationId: deleteAdGroup
      summary: Delete an Ad Group
      description: >-
        Deletes an ad group from a campaign.
      tags:
        - Ad Groups
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/adGroupId'
      responses:
        '204':
          description: Ad group deleted successfully
        '404':
          description: Ad group not found
  /accounts/{account_id}/ads:
    get:
      operationId: listAds
      summary: List Ads
      description: >-
        Lists ads in a Reddit Ads account or ad group, returning ad IDs,
        names, status, creative content, and review status.
      tags:
        - Ads
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/cursor'
        - name: ad_group_id
          in: query
          description: >-
            Filter ads by ad group ID.
          schema:
            type: string
      responses:
        '200':
          description: List of ads
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ad'
                  cursor:
                    type: string
                    description: >-
                      Pagination cursor for the next page.
        '401':
          description: Authentication required
    post:
      operationId: createAd
      summary: Create an Ad
      description: >-
        Creates a new ad with creative content within an ad group.
      tags:
        - Ads
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdInput'
      responses:
        '201':
          description: Ad created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
        '400':
          description: Invalid ad data
  /accounts/{account_id}/ads/{ad_id}:
    get:
      operationId: getAd
      summary: Get an Ad
      description: >-
        Fetches detailed information about a specific ad including
        creative content, status, and review information.
      tags:
        - Ads
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/adId'
      responses:
        '200':
          description: Ad details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
        '404':
          description: Ad not found
    put:
      operationId: updateAd
      summary: Update an Ad
      description: >-
        Updates an existing ad's creative content and configuration.
      tags:
        - Ads
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/adId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdInput'
      responses:
        '200':
          description: Ad updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ad'
        '400':
          description: Invalid ad data
    delete:
      operationId: deleteAd
      summary: Delete an Ad
      description: >-
        Deletes an ad from an ad group.
      tags:
        - Ads
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/adId'
      responses:
        '204':
          description: Ad deleted successfully
        '404':
          description: Ad not found
  /accounts/{account_id}/custom_audiences:
    get:
      operationId: listCustomAudiences
      summary: List Custom Audiences
      description: >-
        Lists custom audiences in a Reddit Ads account. Custom audiences
        allow targeting specific users based on email lists, mobile
        device IDs, or website visitor data.
      tags:
        - Custom Audiences
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: List of custom audiences
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomAudience'
                  cursor:
                    type: string
                    description: >-
                      Pagination cursor for the next page.
        '401':
          description: Authentication required
    post:
      operationId: createCustomAudience
      summary: Create a Custom Audience
      description: >-
        Creates a new custom audience for targeting in ad campaigns.
      tags:
        - Custom Audiences
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomAudienceInput'
      responses:
        '201':
          description: Custom audience created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomAudience'
        '400':
          description: Invalid audience data
  /accounts/{account_id}/custom_audiences/{audience_id}:
    get:
      operationId: getCustomAudience
      summary: Get a Custom Audience
      description: >-
        Fetches detailed information about a specific custom audience.
      tags:
        - Custom Audiences
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: audience_id
          in: path
          required: true
          description: >-
            The unique identifier of the custom audience.
          schema:
            type: string
      responses:
        '200':
          description: Custom audience details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomAudience'
        '404':
          description: Custom audience not found
    put:
      operationId: updateCustomAudience
      summary: Update a Custom Audience
      description: >-
        Updates an existing custom audience's configuration and user list.
      tags:
        - Custom Audiences
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: audience_id
          in: path
          required: true
          description: >-
            The unique identifier of the custom audience.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomAudienceInput'
      responses:
        '200':
          description: Custom audience updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomAudience'
    delete:
      operationId: deleteCustomAudience
      summary: Delete a Custom Audience
      description: >-
        Deletes a custom audience from the account.
      tags:
        - Custom Audiences
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: audience_id
          in: path
          required: true
          description: >-
            The unique identifier of the custom audience.
          schema:
            type: string
      responses:
        '204':
          description: Custom audience deleted
        '404':
          description: Custom audience not found
  /accounts/{account_id}/pixels:
    get:
      operationId: listPixels
      summary: List Conversion Pixels
      description: >-
        Lists conversion pixels (Reddit Pixel) in a Reddit Ads account.
        Pixels are used to track website visitors and conversions for
        attribution and optimization.
      tags:
        - Conversions
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: List of conversion pixels
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversionPixel'
        '401':
          description: Authentication required
  /accounts/{account_id}/conversions/events:
    post:
      operationId: sendConversionEvents
      summary: Send Conversion Events
      description: >-
        Sends server-side conversion events to the Reddit Ads Conversions
        API (CAPI). This enables advertisers to track conversions that
        occur on their servers without relying solely on the Reddit Pixel.
      tags:
        - Conversions
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionEventBatch'
      responses:
        '200':
          description: Conversion events accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Confirmation message.
        '400':
          description: Invalid event data
  /targeting/interests:
    get:
      operationId: listInterests
      summary: List Interest Targeting Options
      description: >-
        Returns available interest categories for ad targeting on the
        Reddit platform.
      tags:
        - Targeting
      responses:
        '200':
          description: List of available interests
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Interest'
  /targeting/communities:
    get:
      operationId: listTargetingCommunities
      summary: List Community Targeting Options
      description: >-
        Returns subreddit communities available for ad targeting.
      tags:
        - Targeting
      parameters:
        - name: q
          in: query
          description: >-
            Search query for filtering communities.
          schema:
            type: string
      responses:
        '200':
          description: List of targetable communities
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TargetingCommunity'
  /targeting/locations:
    get:
      operationId: listLocations
      summary: List Location Targeting Options
      description: >-
        Returns available geographic locations for ad targeting,
        including countries, regions, and metro areas.
      tags:
        - Targeting
      parameters:
        - name: q
          in: query
          description: >-
            Search query for filtering locations.
          schema:
            type: string
      responses:
        '200':
          description: List of targetable locations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Location'
  /accounts/{account_id}/reports:
    post:
      operationId: createReport
      summary: Create a Performance Report
      description: >-
        Generates a performance report for campaigns, ad groups, or ads
        in the specified account. Reports include metrics such as
        impressions, clicks, conversions, and spend.
      tags:
        - Reporting
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportRequest'
      responses:
        '200':
          description: Report data generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportResponse'
        '400':
          description: Invalid report parameters
  /accounts/{account_id}/funding_instruments:
    get:
      operationId: listFundingInstruments
      summary: List Funding Instruments
      description: >-
        Lists the funding instruments (payment methods) associated
        with the specified Reddit Ads account.
      tags:
        - Funding
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: List of funding instruments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FundingInstrument'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        Reddit Ads API uses OAuth 2.0 for authentication. Access tokens
        are obtained via the authorization code flow.
      flows:
        authorizationCode:
          authorizationUrl: https://www.reddit.com/api/v1/authorize
          tokenUrl: https://www.reddit.com/api/v1/access_token
          scopes:
            ads: Access to ads management endpoints
  parameters:
    accountId:
      name: account_id
      in: path
      required: true
      description: >-
        The unique identifier of the Reddit Ads account.
      schema:
        type: string
    campaignId:
      name: campaign_id
      in: path
      required: true
      description: >-
        The unique identifier of the campaign.
      schema:
        type: string
    adGroupId:
      name: ad_group_id
      in: path
      required: true
      description: >-
        The unique identifier of the ad group.
      schema:
        type: string
    adId:
      name: ad_id
      in: path
      required: true
      description: >-
        The unique identifier of the ad.
      schema:
        type: string
    pageSize:
      name: page_size
      in: query
      description: >-
        The maximum number of items to return per page (default 25, max 100).
      schema:
        type: integer
        default: 25
        minimum: 1
        maximum: 100
    cursor:
      name: cursor
      in: query
      description: >-
        A pagination cursor for retrieving the next page of results.
      schema:
        type: string
  schemas:
    Account:
      type: object
      description: >-
        A Reddit Ads account containing campaigns and billing information.
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the account.
        name:
          type: string
          description: >-
            The name of the advertising account.
        status:
          type: string
          description: >-
            The current status of the account.
          enum:
            - ACTIVE
            - SUSPENDED
            - CLOSED
        currency:
          type: string
          description: >-
            The account's billing currency (ISO 4217).
        timezone:
          type: string
          description: >-
            The account's timezone for reporting.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the account was created.
        attribution_type:
          type: string
          description: >-
            The attribution model used for conversion tracking.
    Campaign:
      type: object
      description: >-
        An advertising campaign that contains ad groups and manages
        budget and scheduling.
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the campaign.
        name:
          type: string
          description: >-
            The name of the campaign.
        status:
          type: string
          description: >-
            The current status of the campaign.
          enum:
            - ACTIVE
            - PAUSED
            - COMPLETED
            - DRAFT
        objective:
          type: string
          description: >-
            The campaign objective.
          enum:
            - BRAND_AWARENESS
            - TRAFFIC
            - CONVERSIONS
            - VIDEO_VIEWS
            - APP_INSTALLS
            - CATALOG_SALES
            - REACH
        daily_budget_micro:
          type: integer
          format: int64
          description: >-
            The daily budget in microcurrency units (1/1,000,000 of
            the currency unit).
        lifetime_budget_micro:
          type: integer
          format: int64
          description: >-
            The lifetime budget in microcurrency units.
        start_time:
          type: string
          format: date-time
          description: >-
            The campaign start time.
        end_time:
          type: string
          format: date-time
          description: >-
            The campaign end time.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the campaign was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the campaign was last updated.
    CampaignInput:
      type: object
      description: >-
        Input for creating or updating a campaign.
      required:
        - name
        - objective
      properties:
        name:
          type: string
          description: >-
            The name of the campaign.
        objective:
          type: string
          description: >-
            The campaign objective.
          enum:
            - BRAND_AWARENESS
            - TRAFFIC
            - CONVERSIONS
            - VIDEO_VIEWS
            - APP_INSTALLS
            - CATALOG_SALES
            - REACH
        daily_budget_micro:
          type: integer
          format: int64
          description: >-
            The daily budget in microcurrency units.
        lifetime_budget_micro:
          type: integer
          format: int64
          description: >-
            The lifetime budget in microcurrency units.
        start_time:
          type: string
          format: date-time
          description: >-
            The campaign start time.
        end_time:
          type: string
          format: date-time
          description: >-
            The campaign end time.
        status:
          type: string
          description: >-
            The desired status of the campaign.
          enum:
            - ACTIVE
            - PAUSED
            - DRAFT
    AdGroup:
      type: object
      description: >-
        An ad group within a campaign that contains ads and targeting
        configuration.
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the ad group.
        campaign_id:
          type: string
          description: >-
            The campaign this ad group belongs to.
        name:
          type: string
          description: >-
            The name of the ad group.
        status:
          type: string
          description: >-
            The current status of the ad group.
          enum:
            - ACTIVE
            - PAUSED
            - DRAFT
        bid_strategy:
          type: string
          description: >-
            The bidding strategy for the ad group.
          enum:
            - AUTOMATIC
            - MANUAL_CPC
            - MANUAL_CPM
            - MANUAL_CPV
        bid_micro:
          type: integer
          format: int64
          description: >-
            The bid amount in microcurrency units.
        start_time:
          type: string
          format: date-time
          description: >-
            The ad group start time.
        end_time:
          type: string
          format: date-time
          description: >-
            The ad group end time.
        targeting:
          $ref: '#/components/schemas/Targeting'
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the ad group was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the ad group was last updated.
    AdGroupInput:
      type: object
      description: >-
        Input for creating or updating an ad group.
      required:
        - campaign_id
        - name
      properties:
        campaign_id:
          type: string
          description: >-
            The campaign to create the ad group in.
        name:
          type: string
          description: >-
            The name of the ad group.
        bid_strategy:
          type: string
          description: >-
            The bidding strategy.
          enum:
            - AUTOMATIC
            - MANUAL_CPC
    

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/reddit/refs/heads/main/openapi/reddit-ads-api-openapi.yml