Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/reddit:reddit-app-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Reddit Advertising App API
version: '3'
x-logo:
url: https://www.redditstatic.com/desktop2x/img/favicon/favicon-32x32.png
description: '## 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. **Note:** 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. See our supported partners. ## 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. All API applications must be authenticated with OAuth2 by creating a developer application and obtaining access and refresh tokens. !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}})
```
> **Note:** 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)
```
> **Important:** 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:
> **Important:** 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
Response | Description
--- | ---
200 | Successfully processed the request. 400 | Request was invalid. See the client error message for specifics. 401 | No bearer token or a bad bearer token was provided. Check your application authentication.'
servers:
- url: https://ads-api.reddit.com/api/v3
description: Reddit AdsAPI Production
tags:
- name: App
description: Information about apps.
paths:
/ad_accounts/{ad_account_id}/apps:
get:
description: 'Retrieve mobile app identifiers previously used in app install campaigns.
Each returned item includes only the `id` field (App Store or Google Play identifier).
## Things to know
- The set reflects apps already used in past campaign activity, not every app you may target in the future.
- `page.token` and `page.size` are accepted for consistency with other list endpoints; pagination is not applied yet, so `pagination.next_url` and `pagination.previous_url` are always null.
Rate Limit
See the rate limits for Campaign Management Read
Policy Slug: ads-campaign-management-read
Window: 60 seconds
Quota: 400 requests'
summary: List Apps By Ad Account
operationId: list_apps_by_ad_account
parameters:
- description: The ad account ID.
in: path
name: ad_account_id
required: true
schema:
$ref: '#/components/schemas/id-2'
- $ref: '#/components/parameters/components_parameters_page_token'
- $ref: '#/components/parameters/components_parameters_page_size'
responses:
'200':
description: A list of apps.
content:
application/json:
schema:
type: object
title: ListAppsByAdAccountResponse
additionalProperties: false
required:
- data
- pagination
properties:
data:
type: array
title: AppsList
items:
$ref: '#/components/schemas/components_schema_app'
pagination:
$ref: '#/components/schemas/components_schema_pagination'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
5XX:
$ref: '#/components/responses/ServerError'
security:
- RedditAPIKey:
- adsread
tags:
- App
/apps/{app_id}/last_fired_at_report:
get:
description: 'Retrieve the last time App Install events fired for a specific app ID.
Rate Limit
See the rate limits for Conversion Signals
Policy Slug: ads-conversion-signals
Window: 60 seconds
Quota: 30 requests'
summary: Get App Last Fired At
operationId: get_app_last_fired_at
parameters:
- description: The app ID.
in: path
name: app_id
required: true
schema:
type: string
responses:
'200':
description: 'A report on an app.
> **Note:** Times are in Coordinated Universal Time (UTC).
'
content:
application/json:
schema:
type: object
title: GetAppLastFiredAtResponse
additionalProperties: false
required:
- data
properties:
data:
$ref: '#/components/schemas/components_schema_app_last_fired_at_report'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
5XX:
$ref: '#/components/responses/ServerError'
security:
- RedditAPIKey:
- adsread
tags:
- App
components:
schemas:
components_errors_404:
type: object
required:
- error
additionalProperties: false
properties:
error:
type: object
required:
- message
additionalProperties: false
properties:
message:
type: string
description: A human friendly error message.
examples:
- Member ID not found
code:
type: integer
description: The error code.
examples:
- 404
components_errors_401:
type: object
required:
- error
additionalProperties: false
properties:
error:
type: object
required:
- message
additionalProperties: false
properties:
message:
type: string
description: A human friendly error message.
examples:
- Bad bearer token provided.
code:
type: integer
description: The error code.
examples:
- 401
components_errors_429:
type: object
required:
- error
additionalProperties: false
properties:
error:
type: object
additionalProperties: false
properties:
code:
type: integer
description: The error code.
examples:
- 429
message:
type: string
description: A human friendly error message.
examples:
- Too Many Requests
components_errors_400:
type: object
required:
- error
additionalProperties: false
properties:
error:
type: object
required:
- message
additionalProperties: false
properties:
code:
type: integer
description: The error code.
examples:
- 400
message:
type: string
description: A human friendly error message.
examples:
- Bad request.
fields:
title: FieldsList
type: array
items:
type: object
required:
- field
- message
additionalProperties: false
properties:
field:
title: FieldName
type: string
description: The field that caused the error.
examples:
- field_name
message:
type: string
description: A human friendly error message.
examples:
- Invalid value.
description: The fields that caused the error.
components_errors_500:
type: object
required:
- error
additionalProperties: false
properties:
error:
type: object
required:
- message
additionalProperties: false
properties:
code:
type: integer
description: The error code.
examples:
- 500
message:
type: string
description: A human friendly error message.
examples:
- Internal Server Error
components_schema_app_last_fired_at_report:
title: AppLastFiredAt
type: object
additionalProperties: false
properties:
mobile_conversion_ad_click:
description: The last time an Ad Click event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_ad_view:
description: The last time an Ad View event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_add_payment_info:
description: The last time an Add Payment Info event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_add_to_cart:
description: The last time an Add to Cart event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_add_to_wishlist:
description: The last time an Add to Wishlist event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_app_launch:
description: The last time an App Launches event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_checkout:
description: The last time a Checkout event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_completed_tutorial:
description: The last time a Completed Tutorial event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_first_time_purchase:
description: The last time a First Time Purchase event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_install:
description: The last time an Install event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_level_achieved:
description: The last time a Level Achieved event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_login:
description: The last time a Login event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_onboard_completed:
description: The last time an Onboard Completed event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_onboard_started:
description: The last time an Onboard Started event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_purchase:
description: The last time a Purchase event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_rate:
description: The last time a Rate event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_reinstall:
description: The last time a Reinstall event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_search:
description: The last time an App Searches event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_sign_up:
description: The last time a Sign Ups event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_spend_credits:
description: The last time a Spend Credits event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_start_trial:
description: The last time a Start Trial event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_subscribe:
description: The last time a Subscribe event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_unlock_achievement:
description: The last time an Unlock Achievement event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
mobile_conversion_view_content:
description: The last time a View Content event fired ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
type:
- string
- 'null'
format: date-time
examples:
- '2023-11-06T00:00:00+00:00'
components_schema_pagination:
type: object
additionalProperties: false
properties:
next_url:
description: 'The full URL for the next page. If not available, the current page is the final page.
> **Important:** The URL should be followed directly. Don''t assume pagination based on the query parameters in the provided URLs.
'
example: https://ads-api.reddit.com/api/v3?page.token=nextToken
type:
- string
- 'null'
readOnly: true
previous_url:
description: 'The full URL for the previous page. If not available, the current page is the first page.
> **Important:** The URL should be followed directly. Don''t assume pagination based on the query parameters in the provided URLs.
'
example: https://ads-api.reddit.com/api/v3?page.token=previousToken
type:
- string
- 'null'
readOnly: true
components_errors_403:
type: object
required:
- error
additionalProperties: false
properties:
error:
type: object
required:
- message
additionalProperties: false
properties:
message:
type: string
description: A human friendly error message.
examples:
- Access not granted for listing profiles.
code:
type: integer
description: The error code.
examples:
- 403
id-2:
description: The ad account ID.
examples:
- t2_123456
type: string
pattern: ^(t2|a2)_.*
readOnly: true
components_schema_app:
title: App
type: object
additionalProperties: false
properties:
id:
type: string
description: The App Store ID or Google Play ID of the app.
examples:
- '310633997'
- com.reddit.frontpage
responses:
BadRequest:
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/components_errors_400'
NotFound:
description: The specified resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/components_errors_404'
Unauthorized:
description: No bearer token or a bad bearer token was provided.
content:
application/json:
schema:
$ref: '#/components/schemas/components_errors_401'
TooManyRequests:
description: Too many requests. See [Rate Limiting](/docs/v3/guides/quick-start/rate-limiting) for header details and best practices.
headers:
RateLimit-Policy:
description: The rate limit policies that apply to this request (IETF "RateLimit header fields for HTTP" draft). Each comma-separated policy is keyed by a public policy name and lists its quota `q` and window in seconds `w`.
schema:
type: string
examples:
- '"custom-audience-ingestion";q=3000;w=900,"custom-audience-ingestion-burst";q=500;w=60'
RateLimit:
description: 'The current rate limit state for each applicable policy (IETF "RateLimit header fields for HTTP" draft): remaining quota `r` and seconds until the window resets `t`. On a 429 the exhausted policy reports `r=0`.'
schema:
type: string
examples:
- '"custom-audience-ingestion";r=0;t=42,"custom-audience-ingestion-burst";r=0;t=5'
content:
application/json:
schema:
$ref: '#/components/schemas/components_errors_429'
Forbidden:
description: Insufficient authentication scopes.
content:
application/json:
schema:
$ref: '#/components/schemas/components_errors_403'
ServerError:
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/components_errors_500'
parameters:
components_parameters_page_token:
description: The token for the page to retrieve.
in: query
name: page.token
schema:
type: string
components_parameters_page_size:
description: The number of items to be returned by page.
in: query
name: page.size
allowEmptyValue: true
schema:
type: integer
maximum: 1000
securitySchemes:
RedditAPIKey:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://www.reddit.com/api/v1/authorize
refreshUrl: https://www.reddit.com/api/v1/access_token
tokenUrl: https://www.reddit.com/api/v1/access_token
scopes:
adsconversions: Post conversion events through the API
adsread: Read advertising data through my account.
adsedit: Write advertising data through my account.
adsdatadeletion: Delete advertising data through my account.
description: Reddit OAuth2 Security Key