/v1/responsesCreate a response
The OpenAI Responses API. Continue a conversation with previous_response_id on any gateway server for 30 days after its last turn. State is kept only while your organization stores prompts; an unknown, expired or unstored id is a 400 previous_response_not_found asking you to resend the full conversation.
Under zero-data-retention routing, continuations are refused (zdr_continuation_disabled) unless your organization opts in. The same path also accepts a WebSocket upgrade (the transport the Codex CLI uses).
Authentication: Bearer API key in the Authorization header
Headers
Idempotency-KeystringA unique string per logical request. A retry with the same key and body replays the first result instead of running again; the same key with a different body is a 409. Keyed responses carry no
usage.cost(a replay must be byte-identical).
Request body
modelstringrequiredA slug from
GET /v1/models.inputstring | array<object>requiredA string, or a list of input items (messages, function calls, function call outputs, reasoning items).
instructionsstringSystem instructions.
previous_response_idstringContinue from an earlier response. Kept 30 days from the last turn, only while your organization stores prompts.
streambooleanmax_output_tokensintegertemperaturenumbertop_pnumbertoolsarray<object>Function tools,
web_search, andtool_searchwithdefer_loadingtools.tool_choicestring | objecttextobjecttext.formattakesjson_schemaorjson_objectfor structured output.reasoningobject{"effort": "..."}and{"summary": "..."}.includearray<string>["reasoning.encrypted_content"]returns encrypted reasoning items to replay in later turns, without server-side state.prompt_cache_optionsobject{"ttl": "12h"}asks for 12-hour prompt caching where the model supports it.storebooleanmetadataobjectproviderobjectOpenRouter's routing-preference object, resolved against the model's own provider routes. Only tightens, never loosens, your organization's policy.
provider
zdrbooleantrueserves only zero-data-retention routes for this request, or refuses with a 403 naming the excluded providers.onlyarray<string>Keep only these providers.
ignorearray<string>Drop these providers.
orderarray<string>Try these providers first, in order; the rest stay as fallbacks.
allow_fallbacksbooleanfalsewithorderserves only the listed providers; withoutorder, only the first eligible route.
gatewayobjectPer-request retry and routing bounds, never sent to a provider. SDKs send it through
extra_body.gateway
retryobjectretry
max_attempts_per_routeintegerCalls per route, including the first. Default 2.
max_total_attemptsintegerCalls in total, including retries and fallbacks. Default 8.
backoffobject{"type": "none"}or{"type": "exponential", "base_delay_ms", "max_delay_ms", "multiplier"}(defaults 500, 8000, 2).
routingobjectrouting
allow_fallbacksbooleanfalsekeeps the first eligible route; no failover.route_idstringPin a route by its opaque handle (
route_+ 64 hex), fromGET /api/models/{slug}/providers.
Responses
200The response. With stream set, Responses events ending in response.completed.
Response
idstringPass as
previous_response_idto continue.objectstringcreated_atintegerstatusenummodelstringproviderstringExperiential extension. The provider that served this request.
outputarray<object>usageanyusage
input_tokensintegerinput_tokens_detailsobjectinput_tokens_details
cached_tokensinteger
output_tokensintegeroutput_tokens_detailsobjectoutput_tokens_details
reasoning_tokensinteger
total_tokensintegercostnumberUSD actually charged to your credits for this request, as a float (promotions and plan discounts already applied).
0on your own provider key.is_byokbooleanTrue when the request ran on your own provider key, which the platform never charges.
cost_detailsobjectPresent only in two cases:
upstream_inference_cost(USD, your own key: the provider's list charge to you) orlist_cost(USD, a platform-funded call charged below list: what it would have cost).cost_details
upstream_inference_costnumberlist_costnumber
400Invalid request. param names the field; code says why (invalid_parameter, unsupported_parameter, unsupported_capability, refusal, previous_response_not_found). Not charged.
Response
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
401The key is missing, malformed, expired or revoked.
Response
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
402The organization must act first: card_required, email_unverified, org_under_review, free_tier_requires_payment or promotion_ended. The message names the step; retrying does not help.
Response
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
403model_not_granted (use an id from GET /v1/models), model_location_not_supported, or a zero-data-retention demand no route can meet.
Response
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
409The Idempotency-Key was reused with a different body, or its original result is gone. Use a fresh key.
Response
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
429insufficient_quota (out of credits, over a spend limit, or the model needs a purchase) and promo_credits_now (a free promotion is used up): add credits, the message names the step. rate_limit_exceeded, free_limit_reached, admission_capacity_exceeded: wait Retry-After seconds and retry.
Response
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
502Every provider route failed before any output (all_routes_failed). Retry with backoff.
Response
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
503gateway_unavailable, gateway_draining, unavailable_route or deadline_exceeded. Retry with backoff, honoring Retry-After when present.
Response
errorobjecterror
messagestringWhat went wrong and how to fix it.
typestringFor example
invalid_request_error,authentication_error,permission_error,rate_limit_error,insufficient_quota,api_error.codestringThe stable error code.
paramstring | nullThe request field at fault, when there is one.
refusal_reasonenumPresent only on
code: refusal.
Request
curl https://api.experientiallabs.ai/v1/responses \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-6-luna", "input": "Name three prime numbers."}'
Response
{
"id": "resp_8a41c2e09f7b4d3a9c6e1f2b5d8a0c47",
"object": "response",
"created_at": 1795132800,
"status": "completed",
"model": "gpt-6-luna",
"provider": "openai",
"output": [
{
"id": "msg_8a41c2e09f7b4d3a9c6e1f2b5d8a0c47",
"type": "message",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "2, 3 and 5.",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 12,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 8,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 20,
"cost": 0.0000052,
"is_byok": false
}
}https://api.experientiallabs.ai/v1/responses