# Reddit Ads on boxd

> Reddit Ads API for managing advertising campaigns, conversions, and account data on Reddit.

- Page: https://boxd.sh/integrations/reddit-ads/
- CLI: `run reddit-ads` (83 commands, 51 marked common)
- SDK: `import { redditAds } from "@boxd/run"`; every parameter and response type is at `@boxd/run/reddit-ads`
- Triggers: none
- Connect: `run auth reddit-ads` (Sign in with Reddit Ads), or https://app.boxd.sh/integrations/detail/reddit_ads
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth reddit-ads      # once: prints a link to connect your account
run reddit-ads           # list its commands
run reddit-ads get-me
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, redditAds } from "@boxd/run";

every("1 hour", async () => {
  const result = await redditAds.getMe();
  console.log(result);
});
```

Run it with `run reddit-ads.run.ts`. Reddit Ads has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run reddit-ads <command> --help` lists the optional ones. "common" marks what `run reddit-ads` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `create-ad-group` | `redditAds.createAdGroup()` | `--ad-account-id` `--data` | 0 | Create a new ad group within a Reddit Ads campaign |
| `create-batch-products` | `redditAds.createBatchProducts()` | `--catalog-id` `--data` | 0 | Create or update multiple products in a catalog in a single batch operation |
| `create-campaign` | `redditAds.createCampaign()` | `--ad-account-id` `--data` | 0 | Create a new Reddit Ads campaign for the specified ad account |
| `create-custom-audience` | `redditAds.createCustomAudience()` | `--ad-account-id` `--data` | 0 | Create a new Custom Audience in Reddit Ads |
| `create-lead-gen-form` | `redditAds.createLeadGenForm()` | `--ad-account-id` `--data` | 0 | Create a new lead generation form in Reddit Ads |
| `create-post` | `redditAds.createPost()` | `--data` `--profile-id` | 0 | Create a new Reddit post for a specified profile |
| `create-product-catalog` | `redditAds.createProductCatalog()` | `--business-id` `--data` | 0 | Create a new product catalog |
| `create-product-feed` | `redditAds.createProductFeed()` | `--catalog-id` `--data` | 0 | Create a new feed for a product catalog |
| `create-product-set` | `redditAds.createProductSet()` | `--catalog-id` `--data` | 0 | Create a new product set in a product catalog |
| `create-saved-audience` | `redditAds.createSavedAudience()` | `--ad-account-id` `--data` | 0 | Create a saved audience for a Reddit Ads ad account with targeting criteria |
| `create-structured-post-creation-job` | `redditAds.createStructuredPostCreationJob()` | `--data` `--profile-id` | 0 | Create a structured post creation job on Reddit Ads |
| `delete-custom-audience` | `redditAds.deleteCustomAudience()` | `--audience-id` | 0 | Delete a Custom Audience by ID from Reddit Ads |
| `delete-product-catalog` | `redditAds.deleteProductCatalog()` | `--catalog-id` | 0 | Delete a product catalog by ID from Reddit Ads |
| `delete-product-feed` | `redditAds.deleteProductFeed()` | `--feed-id` | 0 | Delete a feed in a catalog by ID from Reddit Ads |
| `delete-product-set` | `redditAds.deleteProductSet()` | `--product-set-id` | 0 | Delete a product set by ID from Reddit Ads |
| `delete-products` | `redditAds.deleteProducts()` | `--catalog-id` `--data` | 0 | Delete multiple products from a Reddit Ads product catalog in a single request |
| `do-geolocation-validations` ·common | `redditAds.doGeolocationValidations()` | — | 2 | Validate a list of geolocations for use in Reddit Ads targeting |
| `do-keyword-validations` | `redditAds.doKeywordValidations()` | `--data` | 0 | Validate a list of keywords for targeting and check their brand safety status |
| `generate-inspiration-creative-summary` | `redditAds.generateInspirationCreativeSummary()` | `--inspiration-creative-id` | 0 | Get AI-generated summary of best practices followed by an inspiration creative ad |
| `get-ad-account` ·common | `redditAds.getAdAccount()` | `--ad-account-id` | 0 | Retrieve details for a specific Reddit ad account by ID |
| `get-ad-account-history` | `redditAds.getAdAccountHistory()` | `--ad-account-id` | 3 | Get changelog history for a Reddit ad account with filtering options |
| `get-ad-group` ·common | `redditAds.getAdGroup()` | `--ad-group-id` | 0 | Get an ad group by its ID from Reddit Ads API |
| `get-app-last-fired-at` ·common | `redditAds.getAppLastFiredAt()` | `--app-id` | 0 | Retrieve the last time mobile conversion events were fired for a specific app ID |
| `get-business` ·common | `redditAds.getBusiness()` | `--business-id` | 0 | Get business details by ID from the Reddit Ads API |
| `get-campaign` ·common | `redditAds.getCampaign()` | `--campaign-id` | 0 | Retrieve a specific Reddit Ads campaign by its ID |
| `get-channel-planning-reach` ·common | `redditAds.getChannelPlanningReach()` | `--duration-days` `--geolocation` | 5 | Retrieve estimated reach data for a given set of targeting parameters |
| `get-child-funding-instruments` ·common | `redditAds.getChildFundingInstruments()` | `--funding-instrument-id` | 2 | Retrieve a list of Funding Instrument Allocations for a parent funding instrument |
| `get-custom-audience` ·common | `redditAds.getCustomAudience()` | `--audience-id` | 0 | Retrieve a custom audience by ID from Reddit Ads API |
| `get-lead-gen-form` ·common | `redditAds.getLeadGenForm()` | `--lead-gen-form-id` | 0 | Retrieve details for a specific lead generation form by ID from Reddit Ads |
| `get-me` ·common | `redditAds.getMe()` | — | 0 | Get the authenticated member's information from the Reddit Ads API |
| `get-pixel-last-fired-at` ·common | `redditAds.getPixelLastFiredAt()` | `--pixel-id` | 0 | Retrieve the last time conversion events were fired for a specific conversion pixel |
| `get-post` ·common | `redditAds.getPost()` | `--post-id` | 0 | Retrieve a promoted or organic Reddit post by its ID |
| `get-product-catalog` ·common | `redditAds.getProductCatalog()` | `--catalog-id` | 0 | Retrieve a specific product catalog by ID from the Reddit Ads API |
| `get-product-feed` ·common | `redditAds.getProductFeed()` | `--feed-id` | 0 | Retrieve metadata for a specific product feed by ID |
| `get-product-set` ·common | `redditAds.getProductSet()` | `--product-set-id` | 0 | Retrieve metadata for a specific product set by ID from the Reddit Ads API |
| `get-profile` ·common | `redditAds.getProfile()` | `--profile-id` | 0 | Retrieve details for a specific profile by ID from the Reddit Ads API |
| `get-report` ·common | `redditAds.getReport()` | `--ad-account-id` `--data` | 2 | Generate a metrics report for ad performance based on specified fields and breakdowns |
| `get-saved-audience` ·common | `redditAds.getSavedAudience()` | `--saved-audience-id` | 0 | Retrieve a saved audience by ID from Reddit Ads API |
| `get-sk-ad-network-availability` ·common | `redditAds.getSkAdNetworkAvailability()` | `--app-id` | 2 | Get SKAdNetwork IDs availability quota for an iOS app |
| `get-structured-post` | `redditAds.getStructuredPost()` | `--post-id` | 0 | Retrieve a structured post by its ID from the Reddit Ads API |
| `list-ad-accounts-by-business` ·common | `redditAds.listAdAccountsByBusiness()` | `--business-id` | 3 | Get a list of ad accounts under a business on Reddit Ads |
| `list-ad-groups` ·common | `redditAds.listAdGroups()` | `--ad-account-id` | 4 | List ad groups for a Reddit ad account |
| `list-ads` | `redditAds.listAds()` | `--ad-account-id` | 3 | List ads by ad account on Reddit Ads platform |
| `list-campaigns` ·common | `redditAds.listCampaigns()` | `--ad-account-id` | 3 | List campaigns by ad account with pagination support |
| `list-carriers` ·common | `redditAds.listCarriers()` | — | 2 | Retrieve all available carriers from Reddit Ads API for targeting purposes |
| `list-catalog-imports` | `redditAds.listCatalogImports()` | `--catalog-id` | 4 | Retrieve all imports for a catalog |
| `list-communities` ·common | `redditAds.listCommunities()` | — | 3 | List targetable communities matched by their names |
| `list-communities-suggestions` | `redditAds.listCommunitiesSuggestions()` | — | 4 | Fetch suggested communities for given community names from Reddit Ads API |
| `list-devices` ·common | `redditAds.listDevices()` | — | 2 | Retrieve all available devices from Reddit Ads API for targeting purposes |
| `list-funding-instruments` ·common | `redditAds.listFundingInstruments()` | `--ad-account-id` | 9 | List funding instruments (payment methods) for a Reddit Ads ad account |
| `list-geolocations` ·common | `redditAds.listGeolocations()` | — | 3 | Fetch a list of geolocations from Reddit Ads API |
| `list-industries` ·common | `redditAds.listIndustries()` | — | 0 | Retrieve all available industries from Reddit Ads API |
| `list-interests` ·common | `redditAds.listInterests()` | — | 0 | Retrieve all available interests from Reddit Ads API for targeting purposes |
| `list-lead-gen-forms` ·common | `redditAds.listLeadGenForms()` | `--ad-account-id` | 2 | List lead generation forms for a Reddit Ads ad account |
| `list-my-businesses` ·common | `redditAds.listMyBusinesses()` | — | 4 | Retrieve details of businesses associated with the provided access token |
| `list-pixels-by-ad-account` | `redditAds.listPixelsByAdAccount()` | `--ad-account-id` | 2 | List pixels by ad account |
| `list-pixels-by-business` | `redditAds.listPixelsByBusiness()` | `--business-id` | 2 | List all pixels associated with a specific business |
| `list-posts` ·common | `redditAds.listPosts()` | `--profile-id` | 4 | List up to 1,000 of the most recent posts for a specified profile |
| `list-product-catalogs` ·common | `redditAds.listProductCatalogs()` | `--business-id` | 0 | Retrieve details for all product catalogs belonging to a business |
| `list-product-feeds` ·common | `redditAds.listProductFeeds()` | `--catalog-id` | 0 | Retrieve metadata for all feeds in a product catalog |
| `list-product-sets` ·common | `redditAds.listProductSets()` | `--catalog-id` | 2 | Retrieve all product sets in a catalog |
| `list-products-in-product-catalog` ·common | `redditAds.listProductsInProductCatalog()` | `--catalog-id` | 5 | Retrieve all products in a Reddit Ads product catalog |
| `list-products-in-product-set` ·common | `redditAds.listProductsInProductSet()` | `--product-set-id` | 6 | Retrieve all products in a Reddit Ads product set |
| `list-profiles-by-ad-account` | `redditAds.listProfilesByAdAccount()` | `--ad-account-id` | 2 | List profiles by ad account from Reddit Ads API |
| `list-profiles-by-business` | `redditAds.listProfilesByBusiness()` | `--business-id` | 2 | List profiles by business |
| `list-saved-audiences` ·common | `redditAds.listSavedAudiences()` | `--ad-account-id` | 2 | List saved audiences for a Reddit ad account |
| `list-structured-posts` ·common | `redditAds.listStructuredPosts()` | `--profile-id` | 5 | List structured posts for a profile or retrieve up to 10 specific structured posts by ID |
| `list-time-zones` ·common | `redditAds.listTimeZones()` | — | 2 | Retrieve all available time zones from Reddit Ads API for campaign scheduling |
| `list-user-custom-audiences` ·common | `redditAds.listUserCustomAudiences()` | `--ad-account-id` | 3 | List all Custom Audiences under an ad account |
| `list3rd-party-audiences` | `redditAds.list3rdPartyAudiences()` | — | 2 | Retrieve all available 3rd party audiences from Reddit Ads API for targeting purposes |
| `query-ad-accounts` ·common | `redditAds.queryAdAccounts()` | `--business-id` | 3 | Query ad accounts by business with optional filtering by actors, assets, roles, or custom filter string |
| `query-funding-instruments-by-business` ·common | `redditAds.queryFundingInstrumentsByBusiness()` | `--business-id` | 4 | Query funding instruments (credit lines) by business with pagination support |
| `search-communities` ·common | `redditAds.searchCommunities()` | — | 3 | Search for Reddit communities based on their name or topic |
| `update-ad-account` ·common | `redditAds.updateAdAccount()` | `--ad-account-id` `--data` | 0 | Update a Reddit ad account configuration |
| `update-business` ·common | `redditAds.updateBusiness()` | `--business-id` `--data` | 0 | Update a business by ID in Reddit Ads |
| `update-campaign` | `redditAds.updateCampaign()` | `--campaign-id` `--data` | 0 | Update a campaign by ID in Reddit Ads |
| `update-custom-audience-users` | `redditAds.updateCustomAudienceUsers()` | `--audience-id` `--data` | 0 | Update users in a Reddit Ads Custom Audience by adding or removing user identifiers |
| `update-post` | `redditAds.updatePost()` | `--data` `--post-id` | 0 | Update a Reddit post by ID |
| `update-product-catalog` ·common | `redditAds.updateProductCatalog()` | `--catalog-id` `--data` | 0 | Update a product catalog's name or attached Pixel IDs in Reddit Ads |
| `update-product-feed` ·common | `redditAds.updateProductFeed()` | `--data` `--feed-id` | 0 | Update a product feed's metadata in Reddit Ads |
| `update-product-set` ·common | `redditAds.updateProductSet()` | `--data` `--product-set-id` | 0 | Update a product set's name and filter rules in Reddit Ads |
| `update-saved-audience` ·common | `redditAds.updateSavedAudience()` | `--data` `--saved-audience-id` | 0 | Update a saved audience by ID in Reddit Ads |
| `update-structured-post` | `redditAds.updateStructuredPost()` | `--data` `--post-id` | 0 | Update a structured post by ID |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.