All endpoints except the Conversions API (CAPI) have been sunsetted. Use v3 endpoints instead for integrations. While support for CAPI v2 will continue, we encourage migration to CAPI v3 to take advantage of new features and long term support.

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. If you do not agree to be bound by these Ads API Terms, then you may not access or otherwise use the Ads API. Your continued use of the Ads API shall constitute your consent to be bound by these Ads API Terms.

Use of the Conversions API is subject to the same agreements as the Ads API, and, also subject to the Advertiser Measurement Program Terms.

Model Hierarchy

The model hierarchy of Reddit's ad platform can be seen in the diagram below.

• Campaigns have many ad groups
• Ad groups have many ads
• Ads are linked to a promoted post
• Promoted posts may be linked to many ads

Data Freshness

All campaign management data is consistent. All reporting data is accurate up to three hours ago. That means fetching all impressions for today at 6pm will pull all data up to 3pm.

Rate Limits

Advertisers may perform 1 request per second.

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.

Changelog

<!-- Add new entries to the top -->

Date	Description
2026-01-22	Added support for PROCESSING as an Effective Status for Campaigns, Ad Groups, and Ads.
2025-09-30	Sunsetted all v2 endpoints except the Conversions API. Migrate to v3 to avoid service disruption.
2019-10-14	Added locations, platforms and slots to ad_group targeting model. These new fields were added for describing placements. Use these instead of placements. placements will be removed in the near future.
2019-07-02	The reporting endpoint no longer provides the unique_impressions and unique_video_fully_viewable_impressions fields.
2019-06-24	Post endpoints removed. Please use the main Reddit APIs for reading posts.

Quick start

Create a developer application

Only business admins can access this interface. Contact one of your business's administrators for help.

Developer applications define the settings that determine how your app authenticates with the Ads API. These settings streamline workflows and enhance campaign management efficiency programmatically, enabling you to build custom tools to create and manage ad campaigns, generate reports, and manage custom audiences.

These settings can only be managed by business admins with a verified account. You can manage your developer applications in Business Manager > Developer Application.

In this interface, you can:

• Add an app: Create or migrate an existing developer application to define the settings for how your app authenticates with the Ads API.
  • Create: Make new developer application credentials for your app.
  • Migrate: Move an existing developer app associated with your Reddit account to manage it in the Ads Manager.
• Edit an app: Change any setting for your application, excluding its app ID and secret.
• Delete your app: Remove this app from your business. 
  Deleting an app will disconnect all third-party services using it from the Ads API. This action can't be undone.

Create an application

1. In the developer application interface, select Add Apps > Create an app.
2. Set up your app.
   • App name: An appropriate and descriptive title. We recommend a name that reflects your business, product, or integration purpose. Avoid generic names like Reddit Integration or Test. 
   • Description (optional): Information about your app.
   • About URL: The URL that provides more information about your business or application.
   • Redirect URL: The URL to authorize access to your application. We recommend setting a path on your business domain, like https://mybusiness.com/oauth/callback.
   • Primary contact: The business admin responsible for this app, who may be contacted for operational updates related to the Ads API. This must be set to a business admin. Here's how to set this permission.
3. When ready, select Create App. This will save your app and generate its secret and app ID.

Migrate an application

Migration will limit your app's scope to the Ads API.

1. In the developer application interface, select Add Apps > Migrate an existing app.
2. Select the app to migrate.
3. Choose a primary contact for your app. This must be set to a business admin.
4. When ready, select Migrate App. This will make your app only available to manage in the developer application interface and remove it from Preferences > Apps.

Things to know

• A member cannot be removed from your business if they're an active primary contact.
• You agree to the Advertising Platform Terms, Developer Terms, and User Agreement when creating or migrating an app.
• Migrating an application will limit your application's scope to only the Ads API.
• After creating your application, finish setup by authenticating it.

Authenticate your developer application

You can set up your developer application to gain access to the Reddit API, letting you develop nifty applications and integrations that seamlessly interact with Reddit's ads platform.

Before you begin, you should have:

• A Reddit Ads account.
• A developer application. You'll need its app ID and secret.
• Access to a terminal application.

1. Authorize your application

Go to your business's developer applications and find your application's app ID. Replace the values in the following link and navigate to it:

https://www.reddit.com/api/v1/authorize?client_id={{App ID}}&response_type=code&state={{State String}}&redirect_uri={{Redirect URL}}&duration={{Duration}}&scope={{Scope}}

• {{App ID}}: The ID of your dev app
• {{State String}}: This value is fully generated by your application. Set it to an unguessable value (no spaces) and validate it after the redirect to detect cross-site request forgeries (CSRF).
  state should be a single opaque value generated by your app and validated on callback. If you need to restore user routing context (for example, post-login redirects), use a nonce-to-stored-state pattern as described here.

• {{Redirect URL}}: The exact redirect URL you set for your dev app. Exactly one redirect URL is supported per app; to route to a custom landing page or restore user state make use of the state field as described above.
  Don't change redirect_uri to redirect_url. This parameter must be used so that the application can correctly route mobile and web application redirects.

• {{Duration}}: The time limit that this access token will expire. You probably want to set this to permanent, but you can set it to temporary to make the access code valid for only one hour.
  If you set this to temporary, you won't be able to refresh this option.

• {{Scope}}: A comma-separated list of actions that can be performed with the access token. Only the following scopes are accepted: adsread, adsconversions, adsedit, adsleadgendownloader.
  If you'd like your token to access everything in the Reddit Ads API, you can set this to adsread,adsconversions,adsedit,adsleadgendownloader. 

Scope	Description
adsconversions	Post conversion events by enabling access to the Conversions endpoint
adsedit	Edit ads data
adsread	Read advertising data for your account
adsleadgendownloader	Read Lead Gen Forms and retrieve leads

Example: Get link based on credentials

Field	Value
App ID	DnvSjQYG9t13lWWOndNqOg
Redirect URL	https://www.reddit.com/prefs/apps
Scope	Post conversion events with the Conversions API (CAPI)
Link	https://www.reddit.com/api/v1/authorize?client_id=DnvSjQYG9t13lWWOndNqOg&response_type=code&state=4f8d7c1b9a2e6d3c5b0f7a1e8c2d9b6a&redirect_uri=https://www.reddit.com/prefs/apps&duration=permanent&scope=adsconversions

Check that the username listed matches the account you want to authorize the app. If the username is correct, select Allow.

If an unexpected username is displayed, you're in an active Reddit session. To fix this, log out of your account, log into the correct account, then revisit the URL.

You will be sent to the redirect URL that you provided earlier. The URL in your address bar will have 2 query parameters: the state and the code. Copy and record the code value and remove the #_ characters at the end of the value, if any.

This code should be used within the next ten minutes and only once per authorization.

Example: Find code value from redirect URL

Redirect URL	Code value
https://notarealbrand.myshopify.com/oauth/callback?state=4f8d7c1b9a2e6d3c5b0f7a1e8c2d9b6a&code=Ve49meZ9oh3lZFY35CEizm3jTsfJeA#_	Ve49meZ9oh3lZFY35CEizm3jTsfJeA

2. Get your access token from the Reddit API

Open a terminal window and execute the following cURL command with your noted values:

curl -X POST https://www.reddit.com/api/v1/access_token \
     -H 'content-type: application/x-www-form-urlencoded' \
     -A '{{Name}}' \
     -u '{{App ID}}:{{Secret}}' \
     -d 'grant_type=authorization_code&code={{Redirect Code}}&redirect_uri={{Redirect URL}}'

Example: Get access token

Field	Value
Name	SGTM-CAPI
App ID	DnvSjQYG9t13lWWOndNqOg
Secret	Ucr7PXIWe_OK_vAsrE0J3kvDJ0faww
Redirect Code	QGRMgx3l54x0s8NT_WdcuSt_Adi9nA
Redirect URL	https://www.reddit.com/prefs/apps
Code	curl -X POST https://www.reddit.com/api/v1/access_token -H 'content-type: application/x-www-form-urlencoded' -A 'SGTM-CAPI' -u 'DnvSjQYG9t13lWWOndNqOg:Ucr7PXIWe_OK_vAsrE0J3kvDJ0faww' -d 'grant_type=authorization_code&code=QGRMgx3l54x0s8NT_WdcuSt_Adi9nA&redirect_uri=https://www.reddit.com/prefs/apps'

If successful, you will receive a response that looks like this:

{
    "access_token": {{Access token}},
    "token_type": "bearer",
    "expires_in": {{Time to expiration in seconds}},
    "refresh_token": {{Refresh token}},
    "scope": {{Scope string}}
}

Record the value for access_token and refresh_token. You'll use access_token to access the Reddit Ads API for either one hour (3600) or one day (86400), based on the value returned in expires_in.

3. (Optional) Refresh your access token

You can use an active access token to maintain continuous access to the API without requiring re-authentication. 

To refresh your token, open a terminal window and execute the following cURL command with your noted values:

curl -X POST https://www.reddit.com/api/v1/access_token \
     -A '{{Name}}' \
     -u '{{App ID}}:{{Secret}}' \
     -d 'grant_type=refresh_token&refresh_token={{Refresh token}}'

Example: Refresh token

Field	Value
Name	SGTM-CAPI
App ID	kmY1CRszT3obFwYeU3uuEw
Secret	rTBVO3UirF-fcwvlMNellSxqkd3wSQ
Refresh Token	90773738700875-TEhYsiu7TO6A6PIWuiweSH_PBW96lw
Code	curl -X POST https://www.reddit.com/api/v1/access_token -A 'SGTM-CAPI' -u 'kmY1CRszT3obFwYeU3uuEw:rTBVO3UirF-fcwvlMNellSxqkd3wSQ' -d 'grant_type=refresh_token&refresh_token=90773738700875-TEhYsiu7TO6A6PIWuiweSH_PBW96lw'

If successful, you will receive a response that looks like this:

{
    "access_token": {{Access token}},
    "token_type": "bearer",
    "expires_in": {{Time to expiration in seconds}},
    "refresh_token": {{Refresh token}},
    "scope": {{Scope string}}
}

Record the value for access_token and refresh_token. You'll use access_token to access the Reddit Ads API for either one hour (3600) or one day (86400), based on the value returned in expires_in.

Authentication

OAuth 2.0: Reddit API Key

Security Scheme Type:	oauth2
OAuth Flow (authorizationCode):	Token URL: https://www.reddit.com/api/v1/access_token Authorization URL: https://www.reddit.com/api/v1/authorize Refresh URL: https://www.reddit.com/api/v1/access_token Scopes: adsconversions: Post conversion events through the API adsleadgendownloader: Read Lead Gen Forms and retrieve leads adsread: Read advertising data through my account.