Kickbacks.ai API reference

Advertiser API

Create and manage campaigns programmatically. API orders enter the same live, price-ranked auction as orders from the web portal.

The base URL for every endpoint in this reference is:

https://kickbacks.ai/api/advertiser/v1

Requests and responses use JSON. For a machine-readable contract, download the OpenAPI 3.1 specification. To delegate the whole workflow—including skill setup and post-create verification—use the single Claude document.

Authentication

Send both credentials as headers on every request. Your key is pre-generated in the advertiser portal under API access and stays hidden until you click Show.

Billing

Campaign writes require an operational billing arrangement. Choose weekly saved-card auto-pay or request separately approved Net 30; neither requires campaign prepayment, and both bill authoritative delivered value.

amount_cents on create is the order's maximum face-value estimate, not an immediate charge. The invoice uses billable delivery targeting ten continuous seconds, with measured dwell accepted from 9.5 seconds, as recorded by the authoritative ledger. Adjustment credits apply automatically to the next finalized invoice.

Errors

Non-2xx responses include detail, either as a string or an object naming the invalid field and reason. Unknown campaign IDs and campaigns owned by other accounts both return 404.

Retrieve account and balance

Returns identity, the complete invoiced-account balance, and live ordering constraints. Call this before creating a campaign instead of hard-coding limits.

access.reporting is operational or degraded. degraded means the daily rollups have fallen behind, so /stats reads fall through to live ledger scans and large or unaligned windows may be slow or refused. Reporting still answers — prefer last_days and narrower windows until it clears.

balance.owed_cents combines unbilled delivered value and finalized unpaid invoices, less posted adjustment credits. billing_profile reports enrollment, tax readiness, payment health, and the next 1st/15th collection date.

Retrieve current component status

Returns passive current state for the API endpoint, site proxy, authentication, campaign creation, reporting, exports, and invoicing. States are operational, degraded, disabled, or unknown. This endpoint makes no write and reports no invented historical uptime percentage.

List creatives

Returns owned creatives (currently bounded to 500) with presentation, moderation, targeting, pacing, allocation-safe inventory, block delivery, and remaining inventory. Collection reads set delivery.metrics_availability to temporarily_unavailable and return ledger-derived billable impressions, clicks, CTR, viewable ticks, unique viewers, spend, and observed served timestamps as null; use bounded /stats or retrieve one creative when those metrics are required. A null is never a measured zero. Inventory is creative-level only when bid_blocks.creative_id proves the allocation; legacy inventory returns allocation_status: campaign_only and campaign totals instead of a fabricated creative remainder.

Retrieve a creative

Returns one creative with the same allocation-safe delivery block. Unknown and cross-account IDs use the same 404 response.

Preview an unfunded creative

Validates a creative without creating a campaign, block, charge, or ledger row. Returns a 24-hour preview_url showing terminal and extension surfaces. The public snapshot carries presentation fields only and can be revoked with DELETE /previews/{preview_token}.

Preview a campaign

Snapshots the current owned creative into the same expiring presentation-only page. Revoke it with DELETE /previews/{preview_token}.

Retrieve delivery stats

Returns stable account-level ledger metrics and a time series. Ask for a window with last_days=N (recommended) or an explicit start/end. Filter by one or more campaign IDs, creative IDs, surfaces, or countries using comma-separated query values. Filters are intersected and every campaign is checked against the authenticated account. For apples-to-apples A/B data, pass group_by=creative with comma-separated creative_id values; every series uses the same UTC [start,end) bucket spine and includes explicit zeroes.

Time resolution

Relative windows — prefer last_days

last_days=N returns the last N complete UTC days and is the cheapest, safest way to read this endpoint. The server computes the bounds, so they are whole-day aligned by construction and served from the pre-aggregated daily rollups. Bounds you build from your own clock usually are not aligned, and a few minutes of drift off midnight silently costs a full ledger scan. last_days=7 is identical to sending no window at all. It cannot be combined with start or end (400, conflicting_window), and it still obeys the per-granularity range ceiling above.

Default window

start and end are optional. Omitting both at day granularity returns the last seven complete UTC days: the exclusive end is normally today’s midnight, and may be a day earlier while that day is still rolling up. Every response echoes the exact start and end it measured, so read those rather than assuming them. Explicit bounds are always honoured verbatim and never rounded.

Stable metric fields

billable_impressions, viewable_ticks, clicks, events, unique_viewers, spend_micros, and ctr on both totals and every point. Total unique viewers are distinct across the entire requested interval; point values are distinct within each bucket and must not be summed.

Which store answered

Every response carries served_from, and it predicts cost. daily_rollup is pre-aggregated closed UTC days — fast, and flat as the account grows. You get it at day or month granularity when both bounds sit on UTC midnight and no country filter is set. ledger is a live scan whose cost grows with window length multiplied by delivery volume; four shapes always need it, by design: granularity=hour, any partial trailing day such as an end of “now”, any country filter, and group_by=creative. For scheduled ingestion, prefer whole-UTC-day bounds and check that served_from is daily_rollup.

Windows that are too expensive

A window that would require a provably oversized live scan is refused immediately with 400 and detail.reason of window_too_costly, rather than being allowed to run until it times out. The detail carries estimated_events, max_events, and usually a retry_with object naming bounds that will work. retry_with never repeats the window you just sent, so it is always safe to follow; it is absent when no alternative window would help.

Create a raw-ledger CSV export

Queues an asynchronous export for a bounded time interval. The default maximum is 31 days and 250,000 rows; operators can lower those limits. Use the same campaign, creative, surface, and country filters as stats.

Retrieve export status

Poll until status is ready or failed. Ready jobs include download_url, row count, size, expiry, and the CSV schema_version the artifact was generated under (ledger-export-v2; jobs queued under an older contract keep reporting theirs). Downloads expire after 24 hours by default.

Download an export

Streams the private CSV through the authenticated API. The response is marked private, no-store and includes X-Kickbacks-Export-Schema plus X-Kickbacks-Content-SHA256 so clients can validate the schema and bytes before parsing. A job that is still running returns 409; an expired job returns 410.

Create a campaign

Creates a campaign and, by default, enters it into the live auction. Set start_paused: true to stage it behind the authoritative serving kill switch until you explicitly resume it. A successful request returns 201.

Parameters

List campaigns

Returns campaigns owned by the authenticated account, including the strongly typed creation_channel provenance field, status, current creative, moderation status, delivered value, block-level delivery, and report links. API-created records are advertiser_api; legacy means the record predates provenance stamping.

Retrieve a campaign

Returns one campaign and its delivery blocks. Sum impressions_served across blocks for total delivery. Block status progresses from queued to serving to exhausted.

Update a campaign

Updates name, ad_line, or both. A new creative is validated and screened before replacing the live creative. To change URL, bid, or size, cancel and create a new campaign.

Pause a campaign

Stops serving while preserving auction position. Only active or paused campaigns can use this operation.

Resume a campaign

Resumes a paused campaign at its existing auction position and delivery state.

Cancel a campaign

Permanently stops delivery. Delivered impressions are billed pro rata; undelivered impressions are never billed. Cancellation cannot be reversed.

Questions or higher limits? support@kickbacks.ai