Docs menu

Docs

Changelog

Every change to the API, newest first. Also a JSON Feed. Changes within /v1 are additive: anything that would break a client is announced here first, with a sunset date.

Self-serve signup, test keys, API key management and usage

· Added

You can now get started without talking to anyone, test for free, and manage your account through the API.

  • Sign up with your email address: the emailed link creates your account with free credits, a live key and a test key, and opens the dashboard (keys, usage, balance, credit packs). AI agents can sign up with POST /v1/agent_signup: they get a test key at once and a live key that works once you confirm by email.
  • Test keys (st_test_…) answer every endpoint from recorded responses, free and deterministic, and reserved "magic" inputs trigger each error code, so integrations and CI can exercise every branch at no cost.
  • API keys have scopes (endpoints, jobs, account:read, admin), optional spend limits per day or month (spend_limit_reached), expiry and IP allowlists, managed through /v1/api_keys.
  • Account and usage: GET /v1/account (balance, plan, the calling key), GET /v1/usage (requests and credits over time by endpoint, key and outcome) and GET /v1/credit_transactions (the ledger). Set low_balance_threshold to get a credits.low email and event.
  • meta.mode says whether a response came from a live or a test key. forbidden is now returned (with details.reason), and a missing key's unauthorized says where to get one.
Contract changes (104)
  • endpoint facebook.transcript: accepts video links
  • endpoint instagram.transcript: accepts video links
  • endpoint instagram.transcript: accepts post links
  • endpoint tiktok.transcript: accepts video links
  • endpoint tiktok.transcript: accepts post links
  • endpoint youtube.transcript: accepts video links
  • error code endpoint_retired added (HTTP 410)
  • error code forbidden added (HTTP 403)
  • error code idempotency_key_in_progress added (HTTP 409)
  • error code idempotency_key_reused added (HTTP 422)
  • error code insufficient_credits: details key credits_required added
  • error code insufficient_credits: details key credits_available added
  • error code invalid_cursor: details key reason added
  • error code invalid_input: details key suggestion added
  • error code invalid_input: details key accepted_params added
  • error code invalid_input: details key url_kind added
  • error code invalid_input: details key url_platform added
  • error code invalid_input: details key accepted_url_kinds added
  • error code invalid_input: details key endpoints added
  • error code invalid_input: details key fields added
  • error code job_not_found added (HTTP 404)
  • error code overloaded: details key retry_after added
  • error code rate_limited: details key retry_after added
  • error code spend_limit_reached added (HTTP 402)
  • header cache-control added
  • header deprecation added
  • header link added
  • header ratelimit added
  • header ratelimit-policy added
  • header sunset added
  • header traceparent added
  • header x-client-request-id added
  • common param fields added
  • warning code deprecated_endpoint added
  • shared param country added
  • shared param lang added
  • shared param since added
  • shared param sort added
  • shared param until added
  • meta fields are part of the locked contract
  • page fields are part of the locked contract
  • error fields are part of the locked contract
  • MCP tool find_endpoint added
  • MCP tool get_transcript added
  • header authorization added
  • error code forbidden: details key reason added
  • error code forbidden: details key required_scope added
  • error code spend_limit_reached: details key api_key_id added
  • error code spend_limit_reached: details key spend_limit added
  • error code spend_limit_reached: details key interval added
  • error code spend_limit_reached: details key used added
  • error code spend_limit_reached: details key credits_required added
  • error code spend_limit_reached: details key resets_at added
  • error code unauthorized: details key signup_url added
  • error code unauthorized: details key agent_signup_url added
  • meta: field mode added
  • MCP tool get_account added
  • error code insufficient_credits: details key max_credits added
  • header idempotency-key added
  • header idempotent-replayed added
  • header location added
  • header prefer added
  • header preference-applied added
  • header webhook-id added
  • header webhook-signature added
  • header webhook-timestamp added
  • event type job.completed added
  • event type job.canceled added
  • event type job.expired added
  • event type credits.low added
  • event type credits.depleted added
  • event type api_key.spend_limit_reached added
  • event type webhook.test added
  • operation DELETE /v1/webhook_endpoints/{id} added (webhook_endpoints.delete)
  • operation GET /v1/events added (events.list)
  • operation GET /v1/events/{id} added (events.get)
  • operation GET /v1/jobs added (jobs.list)
  • operation GET /v1/jobs/{id} added (jobs.get)
  • operation GET /v1/jobs/{id}/results added (jobs.results.list)
  • operation GET /v1/jobs/{id}/results.jsonl added (jobs.results.download)
  • operation GET /v1/webhook_endpoints added (webhook_endpoints.list)
  • operation GET /v1/webhook_endpoints/{id} added (webhook_endpoints.get)
  • operation GET /v1/webhook_endpoints/{id}/deliveries added (webhook_endpoints.deliveries.list)
  • operation PATCH /v1/webhook_endpoints/{id} added (webhook_endpoints.update)
  • operation POST /v1/events/{id}/redeliver added (events.redeliver)
  • operation POST /v1/jobs added (jobs.create)
  • operation POST /v1/jobs/{id}/cancel added (jobs.cancel)
  • operation POST /v1/webhook_endpoints added (webhook_endpoints.create)
  • operation POST /v1/webhook_endpoints/{id}/rotate_secret added (webhook_endpoints.rotate_secret)
  • operation POST /v1/webhook_endpoints/{id}/test added (webhook_endpoints.test)
  • MCP tool create_job added
  • MCP tool get_job added
  • endpoint tiktok.profile added (/v1/tiktok/profile)
  • resource profile is live
  • MCP tool get_profile added
  • endpoint instagram.post added (/v1/instagram/post)
  • resource post is live
  • MCP tool get_post added
  • endpoint facebook.search_ads added (/v1/facebook/search_ads)
  • resource ad is live
  • MCP tool search added
  • endpoint youtube.comments added (/v1/youtube/comments)
  • resource comment is live
  • MCP tool list_comments added

Request conventions, richer errors and response metadata

· Changed

Every endpoint now follows the same request conventions, and every response tells you more about itself.

  • Unknown parameters are rejected with invalid_input, free, naming the parameter and the one you most likely meant (username → handle). Previously they were ignored. Common parameters (max_age, fields) are always known.
  • Errors carry everything needed to react without parsing the message: status, retryable, param, remediation, doc_url, details (for example credits_required, or the endpoint a link belongs to) and charged (always false). retry-after is never sent on credit errors.
  • A link of the wrong kind (a profile link sent to a video endpoint, a link from another platform) is answered with the endpoint that takes it.
  • meta gains input (what your url resolved to), credits_remaining, client_request_id and warnings.
  • fields selects only the fields you need, after the cache, at no cost.
  • Lists gain page.end_reason and a Link: rel="next" header; since stops paging on newest-first lists.
  • Headers: send x-client-request-id to have your own ID echoed and logged, and traceparent to match traces. RateLimit-Policy and RateLimit describe the account's runaway-protection ceiling, and Cache-Control: max-age works like max_age.
  • Deprecated endpoints will announce themselves with Deprecation and Sunset headers and a warning, and answer endpoint_retired after their sunset. This changelog is also a JSON Feed.

Background jobs and batches, webhooks, events and Idempotency-Key

· Added

Run many requests, or one long one, without holding a connection open, and hear back when they are done.

  • Jobs: POST /v1/jobs runs a batch of endpoint requests in the background, at each endpoint's own price, and max_pages walks a whole list server-side. With ?wait a short job answers inline (a synchronous batch); otherwise poll GET /v1/jobs/{id} (free), page through GET /v1/jobs/{id}/results as items finish, or download every result from the job's signed results_url. Prefer: respond-async turns any endpoint request into a one-request job.
  • Credits are set aside per job (max_credits) and charged per item as it ends; failed items are free. A key's spend limit holds through its jobs, and a test key's jobs answer from recorded responses, free.
  • Webhooks (Standard Webhooks signatures, retried for days, secrets rotated without downtime) deliver job.completed, job.canceled, job.expired, credits.low, credits.depleted and api_key.spend_limit_reached; /v1/events lists every event and redelivers one on request.
  • Idempotency-Key on every POST: retrying with the same key and body never repeats the work.
  • The SDKs gain jobs, webhookEndpoints and events, a create-and-wait helper and webhook signature verification.