Skip to main content
POST
Create Response

Authorizations

x-api-key
string
header
required

Body

application/json

Request body for the Responses API (POST /v1/responses).

OpenAI-Responses-compatible: point a standard OpenAI client at https://api.parallel.ai/v1 with your Parallel API key and set model to parallel. The fields below are the ones Parallel acts on; other OpenAI request fields (tools, tool_choice, temperature, top_p, max_output_tokens, parallel_tool_calls, truncation, store, user, include) are accepted for compatibility but have no effect.

model
string
required

The model to run. parallel is the only supported value (matched case-insensitively); any other value is rejected. To trade response time for answer quality, set reasoning.effort (low/medium/high) rather than changing the model name.

Example:

"parallel"

input
required

The input to generate a response for: a plain string, or a list of role/content messages that includes at least one user message. Must be non-empty, and only text content is supported. input and instructions together may total at most 20,000 characters.

Example:

"What are the latest developments in fusion energy?"

instructions
string | null

System instructions for the model.

previous_response_id
string | null

ID of a previous response to use as conversation context.

stream
boolean | null

Whether to stream the response.

text
ResponseTextConfig · object | null

Configuration for text output, including structured output.

metadata
Metadata · object | null

Arbitrary key-value pairs, echoed back on the Response object. Useful for tagging requests. At most 16 keys; keys up to 64 characters, values up to 512 characters.

reasoning
ResponseReasoningConfig · object | null

Reasoning configuration. effort (low/medium/high) controls how much research is performed; defaults to medium.

background
boolean | null

Background mode is not supported: requests with background=true are rejected with a 422 validation error. Use the Task API (POST /v1/tasks/runs) for long-running work.

Response

Returns a Response object for non-streaming requests (application/json), or a stream of OpenAI Responses streaming events (text/event-stream) when stream=true is set in the request.

A response from the parallel model. A completed response contains a single assistant message whose text is annotated with URL citations grounding the answer.

id
string
required
created_at
number
required
object
string
required
Allowed value: "response"
output
ResponseOutputMessage · object[]
required
parallel_tool_calls
boolean
required
error
ResponseError · object | null

Details of a failed response.

incomplete_details
IncompleteDetails · object | null

Details about why the response is incomplete.

instructions
string | null
metadata
Metadata · object | null
model
string
default:parallel
Allowed value: "parallel"
temperature
number | null
tool_choice
string
default:auto
tools
any[]
top_p
number | null
background
boolean | null
completed_at
number | null
conversation
null
max_output_tokens
integer | null
max_tool_calls
integer | null
moderation
Moderation · object | null

Moderation results for the response input and output, if moderated completions were requested.

previous_response_id
string | null
prompt
null
prompt_cache_key
string | null
prompt_cache_retention
enum<string> | null
Available options:
in_memory,
24h
reasoning
ResponseReasoningConfig · object | null

Reasoning configuration (OpenAI-compatible subset).

safety_identifier
string | null
service_tier
enum<string> | null
Available options:
auto,
default,
flex,
scale,
priority
status
enum<string> | null
Available options:
completed,
failed,
in_progress,
cancelled,
queued,
incomplete
text
ResponseTextConfig · object | null

Text output configuration. By default the response is plain text; for structured output set format to {"type": "json_schema", "name": ..., "schema": {...}}. The json_object format is accepted for compatibility but produces plain text.

top_logprobs
integer | null
truncation
enum<string> | null
Available options:
auto,
disabled
usage
ResponseUsage · object | null

Estimated token usage, populated for OpenAI SDK compatibility. Counts are approximate; Parallel bills per request, not per token.

user
string | null