> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/reddit-ads.md).

# Reddit Ads

Reddit Ads is Reddit's advertising platform. Create and manage campaigns, ad groups and ads, and pull performance reporting from your AI workflows.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector  | Authentication |
| ---------- | -------------- |
| Reddit Ads | OAuth sign-in  |

### Reddit Ads

Connect to Reddit Ads to create and manage campaigns, ad groups and ads, and pull performance reporting.

#### Set up in Reddit Ads

1. Use a Reddit Ads account with access to the records and operations that your workflow needs.
2. Register or select the OAuth application described in the fields below. Add the redirect URI displayed in StackAI to that application and retain its client ID and secret, where required.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **Reddit Ads**.
2. Complete the connector configuration below. If you do not have access to these settings, ask your StackAI administrator to configure the connector.
3. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
4. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connector configuration**

| StackAI field | Required  | What to enter                                                                                                                                                                                                                  |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| OAuth Scopes  | Read-only | OAuth scopes requested from Reddit: 'adsread' (read) and 'adsedit' (write). This value is shown for reference; it is not an editable credential.                                                                               |
| Client ID     | Yes       | The client ID from your Reddit Ads app registration. Register your app in Reddit Ads Manager under Business > Developer Portal. [Provider instructions](https://ads-api.reddit.com/docs/v3/guides/quick-start/create-dev-app). |
| Client Secret | Yes       | The client secret from your Reddit Ads app registration.                                                                                                                                                                       |
| Redirect URI  | Read-only | Use this redirect URI when configuring your OAuth application. This value is shown for reference; it is not an editable credential.                                                                                            |

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **Reddit Ads** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### Create Campaign

Create a new Reddit ad campaign in your ad account. The campaign is created paused by default so you can review it before it spends.

**Required permissions:** `adsread`, `adsedit`.

#### Inputs

| Field                         | Type            | Required | Description                                                                                                                                                                                                                                                     |
| ----------------------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ad account                    | select (string) | Yes      | The Reddit ad account to create the campaign in. Options load from the selected connection.                                                                                                                                                                     |
| Campaign name                 | string          | Yes      | A name to identify this campaign in Reddit Ads Manager.                                                                                                                                                                                                         |
| Objective                     | select (string) | Yes      | What you want the campaign to achieve, for example traffic (clicks) or conversions. Available values: App Installs, Brand Awareness, Catalog Sales, Clicks (Traffic), Conversions, Impressions (Awareness), Lead Generation, Sales, Video Viewable Impressions. |
| App store ID                  | string          | No       | The Apple App Store numeric ID or Google Play package name. Required for app install campaigns; use the same app ID on every ad group.                                                                                                                          |
| Funding instrument            | select (string) | Yes      | The payment method that funds this campaign. Options load from the selected connection.                                                                                                                                                                         |
| Initial status                | select (string) | No       | Whether the campaign starts paused (recommended) or active immediately. Available values: Paused (recommended), Active. Default: PAUSED.                                                                                                                        |
| Campaign budget optimization  | boolean         | No       | Let Reddit distribute one campaign-level budget across ad groups automatically. Cannot be changed after creation. Default: false.                                                                                                                               |
| Conversion pixel              | select (string) | No       | The Reddit pixel used to measure conversions. Required when campaign budget optimization is on. Options load from the selected connection.                                                                                                                      |
| Optimization goal             | string          | No       | The event Reddit should optimize for. Required for conversion and video view campaigns when campaign budget optimization is on.                                                                                                                                 |
| Conversion attribution window | select (string) | No       | How long after a click or view conversions count. For CBO conversion goals, including catalog purchases, choose 7-day click and 1-day view. Available values: 7-day click, 7-day click and 1-day view.                                                          |
| Budget type                   | select (string) | No       | Whether the campaign budget below is per day or for the campaign's lifetime (CBO campaigns only). Available values: Daily budget, Lifetime budget.                                                                                                              |
| Budget amount                 | number          | No       | The campaign budget in your account currency (for example 50 means 50 USD per day for a daily budget). CBO campaigns only.                                                                                                                                      |
| Bid strategy                  | select (string) | No       | How Reddit should bid for you (CBO campaigns only). Available values: Bidless (automatic), Maximize volume, Target cost per result.                                                                                                                             |
| Bid type                      | select (string) | No       | The billable event you bid on, such as per click or per thousand impressions (CBO campaigns only). Available values: Cost per click (CPC), Cost per 1,000 impressions (CPM), Cost per 6-second video view (CPV6), Cost per 15-second video view (CPV15).        |
| Bid amount                    | number          | No       | How much to pay per bidding event, in your account currency (CBO with manual bidding only).                                                                                                                                                                     |
| Lifetime spend cap            | number          | No       | A hard lifetime spending limit for the campaign, in your account currency.                                                                                                                                                                                      |
| Start time                    | datetime        | Yes      | When the campaign should start delivering. Required when campaign budget optimization is on.                                                                                                                                                                    |
| End time                      | datetime        | No       | When the campaign should stop delivering. Required for a lifetime budget; optional for a daily budget.                                                                                                                                                          |

#### Outputs

| Field             | Type   | Description                                             |
| ----------------- | ------ | ------------------------------------------------------- |
| Campaign ID       | string | The id of the created campaign.                         |
| Name              | string | The campaign name.                                      |
| Configured status | string | The status you set on the campaign.                     |
| Effective status  | string | The campaign's real delivery status computed by Reddit. |

### Update Campaign

Change a live Reddit campaign's name, status, budget, schedule or funding without recreating it.

**Required permissions:** `adsread`, `adsedit`.

#### Inputs

| Field              | Type            | Required | Description                                                                                                                                                                                  |
| ------------------ | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ad account         | select (string) | Yes      | The ad account that owns the campaign. Options load from the selected connection.                                                                                                            |
| Campaign           | select (string) | Yes      | The campaign to update. Options load from the selected connection.                                                                                                                           |
| New name           | string          | No       | A new name for the campaign. Leave empty to keep the current name.                                                                                                                           |
| Status             | select (string) | No       | Set the campaign to active, paused or archived. Leave empty to keep the current status. Available values: Active, Paused, Archived.                                                          |
| Funding instrument | select (string) | No       | Switch the payment method that funds this campaign. Options load from the selected connection.                                                                                               |
| Budget amount      | number          | No       | New campaign budget in your account currency (CBO campaigns only).                                                                                                                           |
| Lifetime spend cap | number          | No       | New lifetime spending limit in your account currency.                                                                                                                                        |
| Bid strategy       | select (string) | No       | Change how Reddit bids for you (CBO campaigns only). Available values: Bidless, Maximize Volume, Target CPX.                                                                                 |
| Bid type           | select (string) | No       | Change the billable event you bid on (CBO campaigns only). Available values: CPC (per click), CPM (per 1,000 impressions), CPV6 (per 6-second video view), CPV15 (per 15-second video view). |
| Bid amount         | number          | No       | New amount to pay per bidding event, in your account currency.                                                                                                                               |
| Start time         | datetime        | No       | New scheduled start time.                                                                                                                                                                    |
| End time           | datetime        | No       | New scheduled end time.                                                                                                                                                                      |

#### Outputs

| Field             | Type   | Description                                             |
| ----------------- | ------ | ------------------------------------------------------- |
| Campaign ID       | string | The id of the updated campaign.                         |
| Configured status | string | The campaign's status after the update.                 |
| Effective status  | string | The campaign's real delivery status computed by Reddit. |

### Create Ad Group

Create an ad group inside a campaign, with its budget, bid, schedule and audience targeting (communities, interests, locations, keywords).

**Required permissions:** `adsread`, `adsedit`.

#### Inputs

| Field                         | Type                      | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ad account                    | select (string)           | Yes      | The ad account that owns the campaign. Options load from the selected connection.                                                                                                                                                                                                                                                                                                                                                                    |
| Campaign                      | select (string)           | Yes      | The campaign this ad group belongs to. Options load from the selected connection.                                                                                                                                                                                                                                                                                                                                                                    |
| Ad group name                 | string                    | Yes      | A name to identify this ad group.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Conversion pixel              | select (string)           | Yes      | The Reddit pixel that measures this ad group's results. Reddit requires one on every ad group. Options load from the selected connection.                                                                                                                                                                                                                                                                                                            |
| Initial status                | select (string)           | No       | Whether the ad group starts paused (recommended) or active. Available values: Paused, Active. Default: PAUSED.                                                                                                                                                                                                                                                                                                                                       |
| Budget type                   | select (string)           | No       | Whether the budget below is per day or for the ad group's lifetime. Available values: Daily spend, Lifetime spend.                                                                                                                                                                                                                                                                                                                                   |
| Budget amount                 | number                    | No       | The ad group budget in your account currency, for example 25 means 25 USD.                                                                                                                                                                                                                                                                                                                                                                           |
| Bid strategy                  | select (string)           | No       | Required for ad-group budgets. With campaign budget optimization, leave empty to inherit or choose the campaign's strategy. Available values: Bidless, Manual bidding, Maximize volume, Target CPX.                                                                                                                                                                                                                                                  |
| Bid type                      | select (string)           | No       | Required for ad-group budgets. With campaign budget optimization, leave empty to inherit or choose the campaign's bid type. Available values: CPC (cost per click), CPM (cost per thousand impressions), CPV (cost per view), CPV6 (cost per 6-second view), CPV15 (cost per 15-second view).                                                                                                                                                        |
| Bid amount                    | number                    | No       | How much to pay per bidding event, in your account currency.                                                                                                                                                                                                                                                                                                                                                                                         |
| Optimization goal             | select (string)           | No       | The event Reddit optimizes for. Fifteen-second video views and landing-page visits require account eligibility; 15-second views use CPV15 bidding. Available values: Page visit, Add to cart, Purchase, Lead, Sign up, Clicks, 6-second video view, 15-second video view, Landing page visit, App install, App sign up, App add payment info, App add to cart, App purchase, App level achieved, App start trial, App subscribe, App first purchase. |
| App store ID                  | string                    | No       | The Apple App Store numeric ID or Google Play package name. Required for app install ad groups; use the same app ID as the campaign.                                                                                                                                                                                                                                                                                                                 |
| Product set ID                | string                    | No       | The existing product set UUID from your Reddit catalog. Required for catalog sales ad groups, including static product ads.                                                                                                                                                                                                                                                                                                                          |
| Shopping ad type              | select (string)           | No       | Choose static or dynamic product ads for catalog sales ad groups. Available values: Static product ads, Dynamic product ads.                                                                                                                                                                                                                                                                                                                         |
| Conversion attribution window | select (string)           | No       | How long after a click or view conversions count. Catalog purchase goals require 7-day click and 1-day view. Available values: 7-day click, 7-day click and 1-day view.                                                                                                                                                                                                                                                                              |
| Target communities            | array                     | No       | Subreddit names to target, for example gaming and pcgaming.                                                                                                                                                                                                                                                                                                                                                                                          |
| Target interests              | array                     | No       | Interest categories to target, for example entertainment and technology.                                                                                                                                                                                                                                                                                                                                                                             |
| Target locations              | array                     | No       | Location codes: country codes like US, regions like US-VA, or Reddit geo ids.                                                                                                                                                                                                                                                                                                                                                                        |
| Target keywords               | array                     | No       | Keywords to target.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Excluded communities          | array                     | No       | Subreddit names to exclude from targeting.                                                                                                                                                                                                                                                                                                                                                                                                           |
| Target devices                | object\_array             | No       | Device targets. App installs require one MOBILE device with IOS or ANDROID matching the app.                                                                                                                                                                                                                                                                                                                                                         |
| Target platforms              | multiple\_select (string) | No       | Platforms where ads appear. App installs require at least one mobile platform, such as MOBILE\_NATIVE. Available values: All platforms, Desktop, Reddit mobile app, Mobile web, Mobile web 3X, Shreddit desktop.                                                                                                                                                                                                                                     |
| Expand targeting              | boolean                   | No       | Allow Reddit to automatically broaden your audience when it predicts better results.                                                                                                                                                                                                                                                                                                                                                                 |
| Start time                    | datetime                  | Yes      | When the ad group should start delivering. An explicit start time is required.                                                                                                                                                                                                                                                                                                                                                                       |
| End time                      | datetime                  | No       | When the ad group should stop delivering. Required for lifetime budgets.                                                                                                                                                                                                                                                                                                                                                                             |

#### Outputs

| Field             | Type   | Description                                             |
| ----------------- | ------ | ------------------------------------------------------- |
| Ad group ID       | string | The id of the created ad group.                         |
| Name              | string | The ad group name.                                      |
| Configured status | string | The status you set on the ad group.                     |
| Effective status  | string | The ad group's real delivery status computed by Reddit. |

### Create Ad

Publish a promoted Reddit post as an ad inside an ad group.

**Required permissions:** `adsread`, `adsedit`.

#### Inputs

| Field             | Type            | Required | Description                                                                                                                |
| ----------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| Ad account        | select (string) | Yes      | The ad account that owns the ad group. Options load from the selected connection.                                          |
| Ad group          | select (string) | Yes      | The ad group this ad belongs to. Options load from the selected connection.                                                |
| Ad name           | string          | Yes      | A name to identify this ad in reporting.                                                                                   |
| Reddit post ID    | string          | Yes      | The id of the existing Reddit post to promote, for example t3\_abc123. Find it in the post's URL or in Reddit Ads Manager. |
| Click-through URL | string          | No       | Where users go when they click the ad. Leave empty to link to the post itself.                                             |
| Initial status    | select (string) | No       | Whether the ad starts paused (recommended) or active. Available values: Paused (recommended), Active. Default: PAUSED.     |

#### Outputs

| Field            | Type   | Description                                                                   |
| ---------------- | ------ | ----------------------------------------------------------------------------- |
| Ad ID            | string | The id of the created ad.                                                     |
| Effective status | string | The ad's real delivery status, usually pending approval right after creation. |
| Preview URL      | string | A link to preview the ad, when Reddit provides one.                           |

### Get Campaign Report

Pull performance metrics (impressions, clicks, spend and more) for your campaigns over a date range.

**Required permissions:** `adsread`.

#### Inputs

| Field       | Type            | Required | Description                                                                                                                            |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Ad account  | select (string) | Yes      | The ad account to report on. Options load from the selected connection.                                                                |
| Start date  | datetime        | Yes      | The beginning of the reporting window, on an hourly UTC boundary.                                                                      |
| End date    | datetime        | Yes      | The end of the reporting window, on an hourly UTC boundary.                                                                            |
| Metrics     | array           | No       | Metrics to include. Defaults to impressions, clicks, spend, CTR and eCPM. Default: \["IMPRESSIONS", "CLICKS", "SPEND", "CTR", "ECPM"]. |
| Group by    | array           | No       | How to group rows, for example by campaign and date. Up to 3 groupings. Default: \["CAMPAIGN\_ID", "DATE"].                            |
| Campaign    | select (string) | No       | Limit the report to a single campaign. Leave empty for all campaigns. Options load from the selected connection.                       |
| Time zone   | string          | No       | The time zone used for date boundaries, for example America/New\_York. Default: UTC.                                                   |
| Page cursor | string          | No       | Continue a previous report from where it stopped.                                                                                      |

#### Outputs

| Field       | Type          | Description                                                                 |
| ----------- | ------------- | --------------------------------------------------------------------------- |
| Report rows | object\_array | The report rows, one per breakdown combination, with the requested metrics. |
| Row count   | integer       | How many rows the report returned.                                          |
| Next cursor | string        | Pass this back to fetch more rows, when present.                            |

### List Campaigns

List the campaigns in an ad account with their status and settings.

**Required permissions:** `adsread`.

#### Inputs

| Field       | Type            | Required | Description                                                                        |
| ----------- | --------------- | -------- | ---------------------------------------------------------------------------------- |
| Ad account  | select (string) | Yes      | The ad account whose campaigns to list. Options load from the selected connection. |
| Page cursor | string          | No       | Continue a previous listing from where it stopped.                                 |

#### Outputs

| Field       | Type          | Description                                               |
| ----------- | ------------- | --------------------------------------------------------- |
| Campaigns   | object\_array | The campaigns found, with id, name, objective and status. |
| Next cursor | string        | Pass this back to fetch the next page, when present.      |

### List Ad Groups

List the ad groups in an ad account with their status, budget and campaign.

**Required permissions:** `adsread`.

#### Inputs

| Field       | Type            | Required | Description                                                                        |
| ----------- | --------------- | -------- | ---------------------------------------------------------------------------------- |
| Ad account  | select (string) | Yes      | The ad account whose ad groups to list. Options load from the selected connection. |
| Page cursor | string          | No       | Continue a previous listing from where it stopped.                                 |

#### Outputs

| Field       | Type          | Description                                              |
| ----------- | ------------- | -------------------------------------------------------- |
| Ad groups   | object\_array | The ad groups found, with id, name, campaign and status. |
| Next cursor | string        | Pass this back to fetch the next page, when present.     |

### List Ads

List the ads in an ad account with their status and destination.

**Required permissions:** `adsread`.

#### Inputs

| Field       | Type            | Required | Description                                                                  |
| ----------- | --------------- | -------- | ---------------------------------------------------------------------------- |
| Ad account  | select (string) | Yes      | The ad account whose ads to list. Options load from the selected connection. |
| Page cursor | string          | No       | Continue a previous listing from where it stopped.                           |

#### Outputs

| Field       | Type          | Description                                              |
| ----------- | ------------- | -------------------------------------------------------- |
| Ads         | object\_array | The ads found, with id, name, ad group, status and post. |
| Next cursor | string        | Pass this back to fetch the next page, when present.     |

## Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

### Ad Account Changed

Fires when something changes in a Reddit ad account: campaign, ad group or ad edits, status changes, budget changes or targeting changes.

Pick the ad account to watch. Optionally narrow which changes fire the trigger by change type (ad account, ad, ad group, audience, bid, budget, campaign, status, targeting); leave it empty to fire on every change.

**Required permissions:** `adsread`.

#### Configuration

| Field        | Type                      | Required | Description                                                                                                                                         |
| ------------ | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ad account   | select (string)           | Yes      | The ad account to watch for changes. Options load from the selected connection.                                                                     |
| Change types | multiple\_select (string) | No       | Change types to watch. Leave empty for all changes. Available values: Ad, Ad account, Ad group, Audience, Bid, Budget, Campaign, Status, Targeting. |

#### Event inputs

| Field   | Type          | Required | Description                               |
| ------- | ------------- | -------- | ----------------------------------------- |
| Changes | object\_array | Yes      | The changes detected since the last poll. |

#### Outputs

| Field   | Type          | Description                               |
| ------- | ------------- | ----------------------------------------- |
| Changes | object\_array | The changes detected since the last poll. |

## Important behavior

If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions.

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/reddit-ads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
