Skip to main content
Version: v3
Important changes on September 21, 2026

On September 21, 2026, the new campaign objectives enums will be rolled out. Support for legacy objective enums will continue to help minimize disruption to existing integrations.

However, developers who store, display, map, or report on objective values should review the mapping table and update their logic to avoid disruption.

Contact us for support or questions.

Important changes on July 13th, 2026

Starting July 13th, 2026, all ad groups and campaign budget optimization (CBO) campaigns require a conversion_pixel_id to be set. Update your campaigns and ad groups to prevent delivery issues. Find your Pixels with List Pixels by Ad Account.

Contact us for support or questions.

View the older API doc site (v2).

The Conversions API (CAPI) now supports offline and app events. See the endpoint changes.

Ads API Terms​

By accessing or using the Ads API and/or associated Reddit Data, you are agreeing that you have read, and that you Agree to comply with and to be bound by, the Ads API Terms and all applicable laws and regulations in their entirety without limitation or qualification.

The Ads API Terms apply to and govern your access to and use of the Ads API and Reddit Data, constitute a legally binding agreement between you and Reddit, and include certain terms that are defined in the Advertising Platform Terms, Developer Terms, and User Agreement.

You may use the Ads API and Reddit Data only in accordance with the Ads API Terms. Use of the Conversions API is subject to the Advertiser Measurement Program Terms in addition to the same agreements as the Ads API. If you do not agree to the Ads API Terms, and Advertiser Measurement Program Terms as applicable, then you must not access or use the Ads API, Conversions API, or Reddit Data.

The Reddit Ads API is open to all developers and does not require allowlisting or approval from Reddit to access. Get started with the API.

API partners working on behalf of advertisers can request support by contacting us. Managed advertisers can request partnership approval by contacting their Reddit Ads expert. Self-service developers interested in joining the Ads API ecosystem can apply to become a partner. Learn more about Reddit's advertising ecosystem partner program.

Overview​

The Reddit Ads API lets advertisers tap into the Reddit Ads Platform to build and manage advertising campaigns and accounts programmatically. By integrating Reddit Ads API into your tooling, you can streamline workflows, reduce operational overhead, and accelerate the creation, optimization, and reporting of Reddit campaigns without needing to step into the Reddit Ads Manager directly.

v3 ERD diagram

Here are two popular ways to use the Reddit Ads API:

  • Postman: A visual client that makes it simpler to set up and start testing requests and responses. This is the fastest way to familiarize yourself with the API if you prefer a point-and-click approach. You can explore our Postman collections.
  • Programmatic access: Use your preferred programming language or command-line tools to create automations and integrations. This approach is ideal if you want to embed API calls into your workflows or build custom tools.

User agents​

Rate-limiting issues often occur if you haven't set your user agent to a unique descriptor. Many default user agents (like “Python/urllib” or “Java”) are drastically limited to encourage unique and descriptive user-agent strings. We recommend following this format for your client's user agent string:

{{Target platform}}:{{Unique app ID}}:{{Version string}} (by /u/{{Your Reddit username}})

Including your version number helps us block old buggy or broken versions of your app safely. Just remember to update this string when you update your version number.

Example
User-Agent: android:com.example.myredditapp:v1.2.3 (by /u/kemitche)

Never lie about your user agent! Don't pretend to be popular browsers or other bots. We'll ban anyone caught in the act.

Pagination​

Paginated endpoints respond with a pagination object containing up to 2 fields:

The URLs for these fields should be followed directly. Don't assume pagination based on the query parameters in the provided URLs.

  • next_url: The full URL to access the next page of the response. If not available, the current page is the final page.
  • previous_url: The full URL to access the previous page of the response. If not available, the current page is the first page.

All endpoints that return a list, such as List Campaigns and Get a Report, will be paginated.

Response types​

ResponseDescription
200Successfully processed the request.
400Request was invalid. See the client error message for specifics.
401No bearer token or a bad bearer token was provided. Check your application authentication.
403Insufficient authentication scopes or the user doesn't have permission. Check the client error message for specifics. If it's a permission issue, ensure the user has the proper permissions assigned to take action.
404Specified resource was not found. Check that correct permissions have been given to the source and that the resource exists.
429Request has exceeded rate limits. For more information on rate limiting and best practices for handling errors, see our rate limiting documentation.
500Server error while processing events. Try again later or use our chat agent if the problem persists.

Authentication​

All API applications must be authenticated with OAuth2 by creating a developer application and obtaining access and refresh tokens.

Limitations​

Future changes may introduce new limitations.

  • Rate limits: Exceeding request limits may result in temporary throttling.
  • Functionality restrictions: Unless explicitly stated, alpha or beta products aren't supported in the Reddit Ads API.

Rate Limiting​

The Reddit Ads API applies rate limits to prevent abuse, maintain stability, and ensure fair usage. Understanding these limits helps you build reliable integrations.

The Conversions API (CAPI) endpoint has unique limits and currently doesn't support the standard rate limiting headers. Refer to Post Conversion Events for more details.

How it works​

Each route or endpoint is assigned to a specific endpoint group. Each group shares a pooled limit, meaning requests to endpoints within the same group count toward a shared limit. This limit is based on the group’s quota policies, each defining a request limit within a specific time window.

Limits are applied to each authorized instance of your application, meaning each user who authorizes your application receives their own set of limits.

Rate limiting headers​

Rate limit data is provided in HTTP headers for each API response.

Monitor these headers to manage request rates and prevent throttling.

RateLimit-Policy header​

Provides the application rate limit policies of the requested route.

RateLimit-Policy: "policy-name-1";q=quota-1;w=window-1,"policy-name-2";q=quota-2;w=window-2
Example

custom-audience-ingestion and custom-audience-ingestion-burst of 3000 requests/900 seconds and 500 requests/60 seconds

RateLimit-Policy: "custom-audience-ingestion";q=3000;w=900,"custom-audience-ingestion-burst";q=500;w=60

RateLimit header​

The remaining requests and the time until reset for each endpoint group.

RateLimit: "policy-name-1";r=remaining-1;t=time-until-reset-1,"policy-name-2";r=remaining-2;t=time-until-reset-2
Example

Remaining requests until reset time. 2134 requests remaining for the custom-audience-ingestion policy, which resets in 723 seconds, and 24 requests remaining for the custom-audience-ingestion-burst policy, which resets in 3 seconds.

RateLimit: "custom-audience-ingestion";r=2134;t=723,"custom-audience-ingestion-burst";r=24;t=3

Rate Limit Endpoint Groups​

Campaign Management Read
Campaign Management Write
Targeting Taxonomy
Custom Audiences Ingestion
SlugQuotaWindow
ads-custom-audience-ingestion3000 requests900 sec
ads-custom-audience-ingestion-burst500 requests60 sec
Endpoints
Billing
SlugQuotaWindow
ads-funding-instruments30 requests60 sec
Endpoints
Business Manager
Leads
SlugQuotaWindow
ads-leads20 requests60 sec
Endpoints
Conversion Signals
SlugQuotaWindow
ads-conversion-signals30 requests60 sec
Endpoints
Reporting
SlugQuotaWindow
ads-reporting60 requests60 sec
Endpoints
Product Catalog
Forecasting
SlugQuotaWindow
ads-forecasting30 requests60 sec
Endpoints
Creative Management
Product Catalog Batch
SlugQuotaWindow
ads-product-catalog-batch150 requests60 sec
Endpoints
Keyword Suggestions
SlugQuotaWindow
ads-keyword-suggestions100 requests60 sec
Endpoints

Best practices​

  • Cache data when working with specialized values or reviewing large data sets frequently.
  • Stagger requests across multiple accounts to avoid sudden traffic spikes.
  • Backfill data only during non-peak business hours, when possible.
  • Include custom User-Agent headers with your request.
  • Design your apps to gracefully handle 429 Too Many Requests responses by implementing fallbacks.
Exponential backoff
max_attempts = 10
attempts = 0

while attempts < max_attempts:
  # Make a request to Ads API
  response = requests.get(request_url, headers = \{"Authorization": "Bearer " + auth_token\})

  # If not rate limited, break out of while loop and continue with the rest of the code
  if response.status_code != 429:
    break

  # If rate limited, wait and try again
  time.sleep((2 ** attempts) + random.random())
  attempts = attempts + 1

Authentication​

Reddit OAuth2 Security Key

Security Scheme Type:

oauth2

OAuth Flow (authorizationCode):

Scopes:

  • adsconversions: Post conversion events through the API

  • adsread: Read advertising data through my account.

  • adsedit: Write advertising data through my account.