Skip to main content
This guide takes you from zero to a live campaign on the Thrad Advertiser API. You’ll create a key, confirm access, pick a creative asset, launch a campaign in a single nested call, manage delivery, and read performance. All paths are relative to the base URL:
Every request is authenticated with your organization’s API key as a Bearer token:
Every amount in this API — budgets, bids, and insights spend — is in integer micros ($1 = 1,000,000). Insights additionally pair each *_micros value with a formatted *_display string. Every timestamp is an ISO 8601 string in UTC (2026-04-02T00:00:00Z), never a Unix integer.
Selling physical products? Connect a product feed in the Thrad Platform so your catalog becomes ad-ready assets — and out-of-stock items pause themselves.
1

Create your API key

In the Thrad Platform dashboard, go to Settings → API keys and create a key. Your organization has one active key; the secret (ak_...) is shown once at creation — copy it immediately.Export it so the cURL examples below can reuse it:
Treat the key like a password. If it leaks, rotate it from Settings → API keys — rotation keeps the previous key valid for a short grace period, then it stops working.
2

Confirm access

Fetch your organization’s default ad account. A 200 confirms the key works and shows the account your campaigns will live under.
200 OK
If the key is missing or invalid, you get a bare 401:
401 Unauthorized
3

Pick a creative asset

Ads don’t carry images — they reference an asset, which supplies the image and the destination URL. List your account’s assets and copy the id of the one you want.
200 OK
The API is read-only on assets — there is no upload endpoint and no inline image anywhere. Create assets in the Thrad Platform dashboard, or connect a product feed to populate them automatically.
Billing must be set up before the next step. Your campaign launch charges a deposit on the organization’s default card — add one in the Platform dashboard first, or the create call returns 400 billing_not_configured (with no charge).
4

Create and launch a campaign

Create the whole campaign tree — campaign, one ad group, one card ad — in a single nested call. Use the asset_id from Step 3 on the ad.This call:
  • requires a default card on the org (else 400 billing_not_configured, no charge),
  • atomically creates the campaign, ad group, and ad,
  • charges a $10 deposit off-session on the default card,
  • submits the campaign to review.
Budgets and bids are integer micros ($1 = 1,000,000). The example below sets a $25.00 budget (25000000) with period: "lifetime" — a single cumulative cap — and a $2.00 max bid (2000000). The minimum budget is 990000 ($0.99); max_bid_micros accepts 100–100000000 ($0.0001–$100).
budget.period is required, and it decides how the amount is enforced. "lifetime" is a one-time cap. Any other value (daily, weekly, monthly, quarterly, yearly) means the budget resets every window with no cumulative ceiling — a weekly $25 campaign spends up to $25 every week until you stop it.
Pass an Idempotency-Key header so a retried request never charges twice.
201 Created
The campaign is now submitted to review: it reads back as status: "paused" with review_status: "in_review". The $10 deposit has been charged. There is no draft state — if the card is declined, the call returns 402 card_declined and the campaign is removed.The ad group and ad created by this call read status: "paused" too, so nothing serves before approval. They flip back to active on their own once the campaign is approved — you don’t need to activate them.The request omitted start_time, so it defaults to ~2 days in the future (the earliest allowed launch window) — the response shows that computed timestamp. Omitting end_time leaves it null, so this lifetime budget simply spends until it is exhausted.
A second POST /v1/campaigns with the same Idempotency-Key replays the original response (there is no expiry window). The same key with a different body returns 409 idempotency_key_reused.
5

Manage delivery once approved

Thrad reviews the campaign. Once it’s approved (review_status becomes approved), you control delivery with the status actions. Sending status in an update body is rejected (400 use_status_action) — always use these endpoints.Pause a running campaign:
Resume a paused campaign:
200 OK
/activate only resumes a paused, approved campaign — it never launches one. Calling it on a campaign still in review returns 400 campaign_not_approved. Calling /pause on a campaign that isn’t running returns 400 campaign_not_running. /archive ends a running or paused campaign.
6

Read performance

Fetch metrics for the campaign. Insights default to the trailing 30-day window and combine Thrad + ChatGPT (OpenAI Ads) supply.
200 OK
Ask for metrics by their output field name — spend_micros, cpc_micros, cpm_micros, ctr_ratio — the same names you get back and the same ones you use in filters[] and sort[]. Each arrives with a formatted *_display companion for showing to people; parse the *_micros integer.

​
Next steps

Authentication

Bearer keys, one active key per org, rotation, and error shapes.

Campaigns

Full nested-create schema, updates, and status actions.

Insights

Granularity, aggregation levels, fields, filters, segments, and supply splits.

Product feeds

Sync your catalog over SFTP so products become ad assets that pause and resume with stock.

​
Rate limits