Skip to main content
D1 answers structured questions about a shared text or JSON-object context. Staging is invitation-only. Sign in to the console, wait for admission, and create an API key. Copy the secret when it is displayed; it cannot be displayed again. Keep API keys on your server, never in a public browser bundle or source control. Check simulated in /v1/models: when true, predictions are random sample answers returned after a short artificial delay. They exercise integration and test-credit accounting; scores, timing and synthetic token counts do not describe a real model. The playground labels these results. Replays still return the original stored answer without another charge. Once deployed, the initial real model uses an uncalibrated baseline. Probabilities are model scores, not verified frequencies or guarantees of correctness. Evaluate them on representative examples before relying on them. A model appears in discovery only when available to that deployment; an empty list means prediction is not ready there.

​
Authentication

Use the staging HTTPS origin supplied with your invitation. All /v1 routes use Authorization: Bearer <API key>. The browser console manages its own session. The quickstart includes a complete request. The API reference provides curl, Python, and JavaScript examples. Generate a new operation key only when deliberately starting a new prediction. The deployment’s OpenAPI schema and local API reference describe its running API.

​
Questions and answers

A request contains model (optional; defaults to "default"), context, and an ordered questions array. Context must be a string or JSON object, not a top-level array or scalar. IDs contain 1–128 ASCII letters, digits, underscores, periods, or hyphens. Question IDs are unique within the request. Prompts and descriptions are nonempty strings. Unknown fields are rejected. Answers preserve question order and IDs. A five-level score can be 2.4; it is not automatically a probability or an integer category. The baseline normalizes scores over fixed answer labels; that computation does not establish probability calibration. Global ceilings are 16 questions, 32 options per choice, 10 levels per score, and 262,144 UTF-8 request-body bytes. Choice and score questions require at least two entries. Deployments and validated releases can impose lower ceilings; use the limits returned by /v1/models. Context, total billable input, and native formatted-input limits are checked separately. An estimate can therefore reject input that is below the byte ceiling. Do not silently truncate rejected input.

​
Estimates, charges, and credit

Send the prediction body to /v1/predictions/estimate to receive model, input_tokens, estimated_cost_usd, metering_version, and pricing_version. An estimate is advisory: it does not reserve credit or pin a later prediction’s price. A successful prediction reports its actual pinned model, ordered answers, and usage with input_tokens, cost_usd, metering_version, and pricing_version. USD amounts are exact decimal strings with nine fractional digits, for example "0.000200000". Preserve them as decimal strings or use decimal/integer arithmetic; do not add balances using binary floating point. Billing counts the context once, then each question prompt, choice description, and score-level description in separate tokenizer calls. IDs, API field names, hidden templates, generated answers, and repeated internal processing are not billed. Text context is preserved. JSON-object context uses deterministic compact UTF-8 serialization described in canonical JSON and money. The model’s metering version identifies the tokenizer and counting convention. In simulated mode, meter_simulated_v1 counts each of these billable fields as ceil(UTF-8 bytes / 4) instead of using a model tokenizer. The request charge rounds up once, after summing billable tokens:
available_usd excludes holds and expired credit. paid_usd and promotional_usd include unspent held credit while its grant is valid; reserved_usd can also contain an in-flight allocation from a grant that expired after acceptance. That reservation does not make the expired grant spendable again. financial_shortfall_usd is a positive amount owed after reversal of already-spent paid credit; spendable paid credit and availability are then zero. Expiring promotional credit is used first, then non-expiring promotional credit, then paid credit.

​
Idempotency, deadlines, and retries

Send a unique nonempty Idempotency-Key of at most 200 characters for every logical prediction. The header is optional, but a request without one cannot use key-based replay. Scope is your account and prediction route. Send the same key and the same full request when recovering from a lost response. Object-key order and JSON whitespace do not matter; question/option order, IDs, and original model selection do. Omitting model and specifying "default" are equivalent. An accepted operation keeps its selected model, tariff, and allocation even if the default model or pricing changes. A replay never starts another inference or settles another charge. Replays still require a valid key and active account and have an independent read limit. An inference pause does not block an otherwise authorized completed replay.
  • 200 means the answer and charge are durably committed.
  • 409 request_in_progress means retry the identical operation after Retry-After (normally one second).
  • 409 idempotency_conflict means the key was used with different input.
  • Accepted terminal failures are replayed, remain uncharged, and need a new key for a deliberate new attempt. Pre-acceptance validation, quota, or insufficient credit rejection does not consume the key.
  • Default replay retention is 24 hours from terminal completion. Afterwards, 409 idempotency_expired prevents new inference until the tombstone expires 30 days from initial acceptance. Never recycle old keys: after tombstone expiry, an old key may be accepted as new work.
The default acceptance-to-settlement deadline is 30 seconds. Orphan recovery starts after 60 seconds from acceptance. Client timeouts include network and validation time too; the examples allow 40 seconds. A client disconnect or intermediary timeout can race successful settlement. Keep the key and request, then replay; do not infer “not charged” from a lost response or immediately create a new operation. These guarantees are at-most-once settlement per accepted operation, not a guarantee of network delivery.

​
Errors and quotas

Errors use this envelope, with a server-generated X-Request-ID header:
Use error.code for handling and preserve request_id when contacting support. Do not parse human-readable message text. Honor Retry-After when present. Unexpected 500 responses and non-JSON errors from network intermediaries can also leave the outcome uncertain. Do not automatically retry billable work with a new key. Account RPM/TPM windows are UTC calendar minutes, so a boundary burst is possible. New authenticated prediction and estimate attempts count toward RPM; accepted prediction tokens count toward TPM. Active reservations count toward account concurrency. Estimates also have a separate tokenization budget. The console shows the account’s effective limits.

​
Usage and pagination

GET /v1/usage accepts start (inclusive), end (exclusive), model, limit, and cursor. Supply timezone-aware ISO 8601 timestamps, preferably UTC Z. Default page size is 50; valid sizes are 1–100. Results use newest-first stable (created_at, id) order and contain {items, next_cursor}. Send next_cursor unchanged with the same filters to continue; null ends the list. Cursors are opaque and account/filter scoped. Never construct or share them between accounts. Each item includes request_id, model, question/token counts, status, charge_usd, pricing_version, created_at, and nullable completed_at. Only successful requests have a charge. Usage contains accepted request metadata, not every rejected HTTP attempt, and never exposes context or answers.

​
Staging payments and data retention

Use the console’s server-defined packages and hosted test-mode checkout. Staging credit purchases do not represent live sales. A successful browser return does not itself grant credit: payment history shows when fulfillment is confirmed. Refunds/reversals remove paid principal; reversing already-spent credit can suspend inference pending account review. Authentication and billing history remain available during suspension. By default the application retains encrypted successful responses and terminal error receipts for 24-hour replay, inference-key tombstones for 30 days, and usage metadata for 90 days. Input bodies are not retained by default. Diagnostic content capture is disabled for invited staging; any later capture must be separately account-scoped, time-limited, and audited. Application email payloads default to 30 days and delivery metadata to 90 days. Financial entries and their minimal deduplication evidence are retained separately rather than expiring with replay. These are application access/retention periods, not promises about every backup or external provider copy. Expired replay data is inaccessible before physical cleanup. Backup and provider retention must be disclosed for the deployed service; do not send data requiring an unconfirmed retention guarantee.