Sign inStart free trial

← All action domains

Reddit ads

15 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Create Reddit ad

reddit_ads.create_adwriteconfirmadmin only

Create an ad in a Reddit ad group. A Reddit ad is a REAL POST published by the account's chosen Reddit profile — it carries that identity publicly and redditors can comment on it. Created PAUSED, so it is not shown to anyone until started.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
adGroupIdstringrequiredThe ad group this ad runs in.
namestringrequiredInternal ad name in Reddit Ads Manager; not shown to redditors.
headlinestringrequiredThe post title redditors actually read. This is the ad.
destinationUrlstring (uri)requiredWhere the click goes. Use a Chirply funnel or booking page to keep the lead in this account.
callToAction"Apply Now" | "Book Now" | "Buy Tickets" | "Contact Us" | "Download" | "Get a Quote" | … 13 moreoptionalText on the ad's button.
imageUrlstring (uri)optionalImage for the ad creative. Omit for a text post.
allowCommentsbooleanoptionalWhether redditors may comment on the ad. Reddit ads are posts, so comments are the norm and switching them off reads as evasive. Default: true
displayUrlstringoptionalShown instead of the destination URL. Must be on the same domain.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.create_ad \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "adGroupId": "example",
    "name": "Example",
    "headline": "example",
    "destinationUrl": "https://example.com"
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_create_ad at https://app.chirply.io/api/mcp, same bearer token, same input.

Create Reddit ad group

reddit_ads.create_ad_groupwriteconfirmadmin only

Create an ad group inside a Reddit campaign, holding the targeting: which subreddits, interests, keywords, locations and custom audiences the ads reach. Created PAUSED; it spends nothing until started.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
campaignIdstringrequiredThe Reddit campaign this ad group belongs to.
namestringrequiredAd group name in Reddit Ads Manager.
dailyBudgetnumberoptionalDaily budget for this ad group in the account's currency. Omit when the campaign holds the budget.
lifetimeBudgetnumberoptionalLifetime budget for this ad group in the account's currency.
bidStrategy"MAXIMIZE_VOLUME" | "TARGET_CPX" | "BIDLESS"optionalHow Reddit bids. MAXIMIZE_VOLUME spends the budget for the most results; TARGET_CPX aims at a cost per result. Default: "MAXIMIZE_VOLUME"
optimizationGoal"CLICKS" | "LEAD" | "PAGE_VISIT" | "PURCHASE" | "SIGN_UP" | "ADD_TO_CART" | … 3 moreoptionalThe action Reddit optimizes delivery toward.
startTimestring (date-time)optionalISO 8601 start for this ad group.
endTimestring (date-time)optionalISO 8601 end for this ad group.
targetingobjectrequiredWho sees the ad: communities, interests, keywords, places and audiences.
targeting.communitiesstring[]optionalSubreddit names to target, without the r/ prefix. Reddit's most distinctive targeting — an ad can run inside the exact communities a buyer already reads. Default: []
targeting.excludedCommunitiesstring[]optionalSubreddits to stay out of entirely. Default: []
targeting.interestsstring[]optionalReddit interest IDs from the interests list. Default: []
targeting.keywordsstring[]optionalKeywords to target. Reddit reports a monthly view count for each suggestion. Default: []
targeting.excludedKeywordsstring[]optionalKeywords that should never trigger this ad. Default: []
targeting.geolocationsstring[]optionalGeolocation IDs from the geolocations list. Empty targets everywhere the account may run. Default: []
targeting.excludedGeolocationsstring[]optionalGeolocation IDs to exclude. Default: []
targeting.customAudienceIdsstring[]optionalCustom audience IDs to include, for example a CRM list synced from this account's contacts. Default: []
targeting.excludedCustomAudienceIdsstring[]optionalCustom audience IDs to exclude — usually existing customers. Default: []
targeting.placementsarray of ("FEED" | "COMMENTS_PAGE")optionalWhere the ad can appear: in the feed, on the comments page, or both. Default: ["FEED"]
targeting.languagesstring[]optionalISO 639-1 language codes. Empty targets all languages. Default: []
targeting.expandTargetingbooleanoptionalLet Reddit widen the audience beyond what's selected when it expects better delivery. Default: false

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.create_ad_group \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "example",
    "name": "Example",
    "targeting": {}
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_create_ad_group at https://app.chirply.io/api/mcp, same bearer token, same input.

Create Reddit campaign

reddit_ads.create_campaignwriteconfirmadmin only

Create a campaign in the connected Reddit ad account, with its budget and objective. The campaign is created PAUSED and spends nothing until it is started separately, but the budget set here is real money on the advertiser's own Reddit payment method once it runs.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
namestringrequiredCampaign name as it appears in Reddit Ads Manager.
objective"CLICKS" | "CONVERSIONS" | "LEAD_GENERATION" | "IMPRESSIONS" | "VIDEO_VIEWABLE_IMPRESSIONS"requiredWhat the campaign optimizes for. CONVERSIONS and LEAD_GENERATION need a Reddit Pixel on the account.
dailyBudgetnumberoptionalDaily budget in the ad account's own currency — the real money this campaign may spend each day.
lifetimeBudgetnumberoptionalTotal budget in the ad account's own currency for the whole campaign run.
fundingInstrumentIdstringoptionalWhich of the ad account's payment methods pays for this. Defaults to the account's servable one.
specialAdCategoriesarray of ("NONE" | "EMPLOYMENT" | "HOUSING" | "CREDIT" | "SOCIAL_ISSUES_ELECTIONS_POLITICS")optionalLegally restricted categories. Declaring these wrongly can cost the advertiser their ad account. Default: []
startTimestring (date-time)optionalISO 8601 start. Omitted starts as soon as Reddit approves it.
endTimestring (date-time)optionalISO 8601 end. Omitted runs until paused or the lifetime budget is spent.
conversionPixelIdstringoptionalReddit Pixel ID used to measure and optimize conversions.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.create_campaign \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example",
    "objective": "CLICKS"
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_create_campaign at https://app.chirply.io/api/mcp, same bearer token, same input.

Disconnect Reddit Ads

reddit_ads.disconnectwriteconfirmadmin only

Remove this account's Reddit authorization. Campaigns already built keep running on Reddit — nothing is paused or deleted there — but Chirply stops reporting on them and can no longer create or change anything until Reddit is reconnected.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.disconnect \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool reddit_ads_disconnect at https://app.chirply.io/api/mcp, same bearer token, same input.

Open Reddit Ads connection

reddit_ads.get_connectionreadadmin only

Read whether this account has connected Reddit Ads, which Reddit ad account and posting profile it works in, and whether the grant is held by a person or a durable System User. Returns identifiers and flags only; never returns tokens.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.get_connection \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool reddit_ads_get_connection at https://app.chirply.io/api/mcp, same bearer token, same input.

Report on Reddit ads

reddit_ads.get_reportreadadmin only

Read delivery figures for this account's Reddit ads over a date range — impressions, clicks, spend, CTR, CPC and conversions — grouped by campaign, date, subreddit, country, placement, keyword or interest. Read-only. Reddit's numbers take up to six hours to settle and late conversions can revise earlier days.

Parameters

FieldTypeRequiredDescription
startsAtstringrequiredISO 8601 start of the reporting window.
endsAtstringrequiredISO 8601 end of the reporting window.
breakdown"CAMPAIGN_ID" | "AD_GROUP_ID" | "AD_ID" | "DATE" | "COMMUNITY" | "COUNTRY" | … 3 moreoptionalHow to group the numbers. COMMUNITY answers the question only Reddit can: which subreddits actually worked. Default: "CAMPAIGN_ID"

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.get_report \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "startsAt": "example",
    "endsAt": "example"
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_get_report at https://app.chirply.io/api/mcp, same bearer token, same input.

List Reddit ad accounts

reddit_ads.list_accountsreadadmin only

List the Reddit businesses and ad accounts the connected Reddit identity can reach, including whether Reddit currently allows each one to run ads. Read-only; spends nothing.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.list_accounts \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool reddit_ads_list_accounts at https://app.chirply.io/api/mcp, same bearer token, same input.

List Reddit campaigns

reddit_ads.list_campaignsreadadmin only

List this account's Reddit campaigns with their ad groups and ads, including each one's live delivery status and any rejection reason from Reddit. Read-only.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.list_campaigns \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool reddit_ads_list_campaigns at https://app.chirply.io/api/mcp, same bearer token, same input.

List Reddit payment methods

reddit_ads.list_fundingreadadmin only

List the payment methods on the connected Reddit ad account and whether Reddit will currently bill each one, with the reason when it will not. Read-only; returns Reddit's own identifiers and limits, never card details.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.list_funding \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool reddit_ads_list_funding at https://app.chirply.io/api/mcp, same bearer token, same input.

Remove Reddit connection

reddit_ads.remove_connectionwriteconfirmadmin only

Remove one saved Reddit authorization from Chirply. Existing Reddit campaigns keep running and may continue spending on Reddit; Chirply no longer reads or changes them through this authorization.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
connectionIdstring (uuid)requiredThe saved Chirply Reddit connection ID to remove.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.remove_connection \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_remove_connection at https://app.chirply.io/api/mcp, same bearer token, same input.

Choose Reddit ad account

reddit_ads.select_accountwriteadmin only

Choose which Reddit ad account this Chirply account works in and which Reddit profile publishes its ads. This decides whose budget later campaigns spend, but by itself changes nothing on Reddit and spends no money.

Parameters

FieldTypeRequiredDescription
businessIdstringrequiredThe Reddit business that owns the ad account.
adAccountIdstringrequiredThe Reddit ad account to work in. Its own payment methods fund every campaign built here.
profileIdstringrequiredThe Reddit profile that publishes this account's ads. Ads are real Reddit posts, so this is the identity redditors see and reply to.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.select_account \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "example",
    "adAccountId": "example",
    "profileId": "example"
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_select_account at https://app.chirply.io/api/mcp, same bearer token, same input.

Use Reddit connection

reddit_ads.select_connectionwriteadmin only

Choose which saved Reddit authorization Chirply uses for account discovery, reporting and future campaign changes. This does not change anything on Reddit and spends no money.

Parameters

FieldTypeRequiredDescription
connectionIdstring (uuid)requiredThe saved Chirply Reddit connection ID to make active.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.select_connection \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_select_connection at https://app.chirply.io/api/mcp, same bearer token, same input.

Start or pause Reddit ads

reddit_ads.set_statuswriteconfirmadmin only

Start, pause or archive a Reddit campaign, ad group or ad. Setting it ACTIVE BEGINS SPENDING the advertiser's real budget on their own Reddit payment method and shows the ad publicly; archiving cannot be undone from here.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
level"campaign" | "ad_group" | "ad"requiredWhich object to change: the whole campaign, one ad group, or a single ad.
idstringrequiredThe Reddit ID of the campaign, ad group or ad.
status"ACTIVE" | "PAUSED" | "ARCHIVED"requiredACTIVE starts delivery and spending, PAUSED stops it, ARCHIVED retires the object.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.set_status \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "level": "campaign",
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "status": "ACTIVE"
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_set_status at https://app.chirply.io/api/mcp, same bearer token, same input.

Find subreddits to target

reddit_ads.suggest_communitiesreadadmin only

Ask Reddit which communities (subreddits) to advertise in, seeded from topic words or a website address. This is Reddit's own suggestion engine and returns each community's subscriber count. Read-only and spends nothing, so it is safe to use as research before any campaign exists.

Parameters

FieldTypeRequiredDescription
topicsstring[]optionalTopic words describing the business or offer, for example "plumbing", "emergency repair". Default: []
websiteUrlstring (uri)optionalA website to base suggestions on — usually the advertiser's own. Often the single most useful input.
searchstringoptionalSearch subreddits by name or topic instead of asking for suggestions.

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.suggest_communities \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "websiteUrl": "https://example.com",
    "search": "example"
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_suggest_communities at https://app.chirply.io/api/mcp, same bearer token, same input.

Find Reddit keywords

reddit_ads.suggest_keywordsreadadmin only

Ask Reddit for keyword ideas seeded from terms you supply, each with Reddit's own monthly view count, and flag any term Reddit does not consider brand safe. Read-only and spends nothing.

Parameters

FieldTypeRequiredDescription
seedsstring[]requiredTerms to base suggestions on, for example "burst pipe", "emergency plumber".
validatebooleanoptionalAlso check each returned keyword against Reddit's brand-safety list. Default: false

Example

curl -X POST https://app.chirply.io/api/v1/actions/reddit_ads.suggest_keywords \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "seeds": [
      "example"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool reddit_ads_suggest_keywords at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=reddit_ads — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.