Create, list, retrieve, update, and control the lifecycle of advertiser campaigns.
A campaign is the top of the advertiser object tree: it carries the budget, schedule, geo targeting, and pricing model, and it owns one or more ad groups, each of which owns one or more ads. Creating a campaign is a single nested call — you send the campaign plus its ad_groups[] (each with its ads[]) in one request, and Thrad creates the whole tree, charges a deposit, and submits it for review.All paths on this page are relative to the base URL https://api.thrad.ai/v1. Every request must send Authorization: Bearer ak_... — see Authentication.
Money on campaign resources is expressed in integer micros, where $1 = 1,000,000. So budget.lifetime_spend_limit_micros: 5000000 is $5.00. This is different from the Insights API, which returns dollar floats. State the unit you mean — micros here, dollars there.
Lifecycle state: active | paused | archived. Change it only through the /activate, /pause, and /archive sub-actions — sending status in a campaign update body is rejected.
Campaign start, as a Unix timestamp in seconds. Always present — if you omit start_time on create, Thrad sets it to roughly two days in the future (the earliest allowed launch window), so a read response is never null here.
Every campaign created through this API is submitted to Thrad for human review. The two status fields are independent:
status is the lifecycle state you control: active | paused | archived.
review_status is the moderation verdict you do not control: in_review | approved | rejected.
A newly created campaign always comes back as status: "paused", review_status: "in_review". It cannot serve or be activated until Thrad approves it. Once approved, review_status becomes approved and you can activate it. If it is rejected, review_status becomes rejected.
Approval (the in_review → approved transition) is performed by Thrad, not through this API. Until a campaign is approved, /activate returns 400 campaign_not_approved.
Creates a campaign together with its ad groups and ads in a single nested request, then submits the campaign for review.
POST /v1/campaigns
This one call does several things atomically:
1
Validate billing
Your organization must have a default card on file. If it does not, the request fails with 400 billing_not_configured and nothing is created.
2
Create the tree
The campaign, its ad_groups[], and each ad group’s ads[] are created together. Each ad’s creative image becomes a stored asset.
3
Charge the deposit
A $10 deposit is charged off-session on your default card. A card decline returns 402 card_declined and the campaign is removed (no lingering draft); a provider outage returns 502 payment_provider_error.
4
Submit for review
The campaign is submitted to Thrad. The response comes back with status: "paused" and review_status: "in_review".
A client-generated key (e.g. a UUID) that makes retries safe. The same key replays the first response indefinitely (there is no expiry window), so a retried create never charges twice. Reusing the same key with a different body returns 409 idempotency_key_reused.
Campaign start, as a Unix timestamp in seconds. Omit to default to roughly two days in the future (the earliest allowed launch window) — the response then comes back with that computed timestamp, never null.
Contains include, an array of location objects. Each entry needs a country_code (ISO 3166-1 alpha-2, e.g. "US") — or an id carrying the same code. See Campaign targeting.
The charging create endpoint is rate-limited to 60 requests/hour per key (on top of the global 1000/hour limit). Always send an Idempotency-Key so a network retry replays the original result instead of charging again.
Updates the mutable fields of a campaign. Only the fields you send are changed.
POST /v1/campaigns/{campaign_id}
Updatable fields are name, description, budget, targeting, start_time, and end_time. Numeric values are re-validated exactly as on create: budget.lifetime_spend_limit_micros must still be >= 990000, and any start_time / end_time must be an integer Unix timestamp. An out-of-range or non-integer value returns 400 invalid_value.
You cannot change status here. Sending status in the body returns 400 use_status_action — use /activate, /pause, or /archive instead. review_status, recurring_frequency, and pricing_model are not updatable either.
A required field (name, budget.lifetime_spend_limit_micros, ad_groups, an ad group’s ads) is missing.
400
invalid_value
A field is the wrong type or out of range — e.g. budget below 990000, max_bid_micros outside 1–100000000, a non-integer timestamp, or mixed creative types in one ad group.
400
use_status_action
status was sent in an update body. Use /activate, /pause, or /archive.
400
billing_not_configured
The organization has no default card; set one up before creating a campaign.
400
campaign_not_approved
/activate was called on a campaign that is not approved and paused.
400
campaign_not_running
/pause was called on a campaign that is not running.
400
cannot_archive
/archive was called on a campaign that is not running or paused.
400
no_ad_account
No ad_account_id was supplied and the organization has zero ad accounts. A supplied-but-unknown ad_account_id returns 404 not_found instead.
401
auth_required
The Authorization header is missing entirely.
401
invalid_api_key
The key is malformed, unknown, or revoked.
402
card_declined
The $10 deposit charge was declined. Nothing is created.
404
not_found
The campaign_id is unknown or belongs to another organization.
409
idempotency_key_reused
The same Idempotency-Key was reused with a different request body.
409
name_conflict
A campaign with that name already exists.
429
rate_limit_exceeded
The 1000/hour key limit (or the 60/hour create limit) was exceeded.
502
payment_provider_error
The payment provider was unavailable. Nothing is created; retry later.
