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. Web grounding is always on, so no tool is needed to search; a web_search tool only restricts the searched domains through its filters. An mcp tool gives the model a remote MCP server to call, and each call is executed and reported as an mcp_call output item. Every other tool is accepted and ignored. data_sources enables data partners in addition to web search. Other OpenAI request fields (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.

tools
(ResponseWebSearchTool · object | ResponseMcpTool · object | object)[] | null

OpenAI tools. Web grounding is always on, so no tool is needed to search; a web_search tool's filters restrict the domains searched and cited (allowed_domains maps to Parallel's source_policy.include_domains, blocked_domains to exclude_domains; set one, not both). An mcp tool gives the model a remote MCP server to call; at most 10 per request. Every other tool is accepted and ignored.

The OpenAI web_search tool. Web grounding is always on, so the tool itself changes nothing; its filters restrict which domains are searched. search_context_size and user_location are accepted and ignored.

data_sources
TaskDataSources · object | null

Data partners to enable for this request, in addition to web search: pay_per_use partners are billed per call, free partners are not. Same names and shape as the Task API's advanced_settings.data_sources; see the Data Sources documentation. Supported when reasoning.effort is medium (the default) or high. A partner name must not collide with an mcp tool's server_label.

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 one web_search_call item per web search the model ran, mcp_list_tools discovery outcomes, and one mcp_call item per MCP tool call it made, followed by 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 | ResponseFunctionWebSearch · object | ResponseMcpCall · object | ResponseMcpListTools · object)[]
required

An assistant message produced by the model.

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
(ResponseWebSearchTool · object | ResponseMcpTool · object)[]

The OpenAI web_search tool. Web grounding is always on, so the tool itself changes nothing; its filters restrict which domains are searched. search_context_size and user_location are accepted and ignored.

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