import requests
url = "https://api.parallel.ai/v1/responses"
payload = {
"model": "parallel",
"input": "What are the latest developments in fusion energy?"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({model: 'parallel', input: 'What are the latest developments in fusion energy?'})
};
fetch('https://api.parallel.ai/v1/responses', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api.parallel.ai/v1/responses")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"parallel\",\n \"input\": \"What are the latest developments in fusion energy?\"\n}")
.asString();curl --request POST \
--url https://api.parallel.ai/v1/responses \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"model": "parallel",
"input": "What are the latest developments in fusion energy?"
}
'{
"id": "<string>",
"created_at": 123,
"object": "response",
"output": [
{
"id": "<string>",
"content": [
{
"annotations": [
{
"end_index": 123,
"start_index": 123,
"title": "<string>",
"type": "url_citation",
"url": "<string>"
}
],
"text": "<string>",
"type": "output_text",
"logprobs": [
{
"token": "<string>",
"bytes": [
123
],
"logprob": 123,
"top_logprobs": [
{
"token": "<string>",
"bytes": [
123
],
"logprob": 123
}
]
}
]
}
],
"role": "assistant",
"status": "in_progress",
"type": "message",
"phase": "commentary"
}
],
"parallel_tool_calls": true,
"error": {
"code": "server_error",
"message": "<string>"
},
"incomplete_details": {
"reason": "max_output_tokens"
},
"instructions": "<string>",
"metadata": {},
"model": "parallel",
"temperature": 123,
"tool_choice": "auto",
"tools": [],
"top_p": 123,
"background": true,
"completed_at": 123,
"conversation": null,
"max_output_tokens": 123,
"max_tool_calls": 123,
"moderation": {
"input": {
"categories": {},
"category_applied_input_types": {},
"category_scores": {},
"flagged": true,
"model": "<string>",
"type": "moderation_result"
},
"output": {
"categories": {},
"category_applied_input_types": {},
"category_scores": {},
"flagged": true,
"model": "<string>",
"type": "moderation_result"
}
},
"previous_response_id": "<string>",
"prompt": null,
"prompt_cache_key": "<string>",
"prompt_cache_retention": "in_memory",
"reasoning": {
"effort": "high"
},
"safety_identifier": "<string>",
"service_tier": "auto",
"status": "completed",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"top_logprobs": 123,
"truncation": "auto",
"usage": {
"input_tokens": 123,
"input_tokens_details": {
"cached_tokens": 123
},
"output_tokens": 123,
"output_tokens_details": {
"reasoning_tokens": 123
},
"total_tokens": 123
},
"user": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Create Response
Create a response.
Generates an answer to the given input, grounded in live web research and
annotated with URL citations. Set model to parallel; reasoning.effort
(low/medium/high) controls how much research is performed, trading
response time for answer quality. Returns an OpenAI-format Response as
application/json, or a text/event-stream of OpenAI Responses SSE
events when stream=true.
import requests
url = "https://api.parallel.ai/v1/responses"
payload = {
"model": "parallel",
"input": "What are the latest developments in fusion energy?"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({model: 'parallel', input: 'What are the latest developments in fusion energy?'})
};
fetch('https://api.parallel.ai/v1/responses', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api.parallel.ai/v1/responses")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"parallel\",\n \"input\": \"What are the latest developments in fusion energy?\"\n}")
.asString();curl --request POST \
--url https://api.parallel.ai/v1/responses \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"model": "parallel",
"input": "What are the latest developments in fusion energy?"
}
'{
"id": "<string>",
"created_at": 123,
"object": "response",
"output": [
{
"id": "<string>",
"content": [
{
"annotations": [
{
"end_index": 123,
"start_index": 123,
"title": "<string>",
"type": "url_citation",
"url": "<string>"
}
],
"text": "<string>",
"type": "output_text",
"logprobs": [
{
"token": "<string>",
"bytes": [
123
],
"logprob": 123,
"top_logprobs": [
{
"token": "<string>",
"bytes": [
123
],
"logprob": 123
}
]
}
]
}
],
"role": "assistant",
"status": "in_progress",
"type": "message",
"phase": "commentary"
}
],
"parallel_tool_calls": true,
"error": {
"code": "server_error",
"message": "<string>"
},
"incomplete_details": {
"reason": "max_output_tokens"
},
"instructions": "<string>",
"metadata": {},
"model": "parallel",
"temperature": 123,
"tool_choice": "auto",
"tools": [],
"top_p": 123,
"background": true,
"completed_at": 123,
"conversation": null,
"max_output_tokens": 123,
"max_tool_calls": 123,
"moderation": {
"input": {
"categories": {},
"category_applied_input_types": {},
"category_scores": {},
"flagged": true,
"model": "<string>",
"type": "moderation_result"
},
"output": {
"categories": {},
"category_applied_input_types": {},
"category_scores": {},
"flagged": true,
"model": "<string>",
"type": "moderation_result"
}
},
"previous_response_id": "<string>",
"prompt": null,
"prompt_cache_key": "<string>",
"prompt_cache_retention": "in_memory",
"reasoning": {
"effort": "high"
},
"safety_identifier": "<string>",
"service_tier": "auto",
"status": "completed",
"text": {
"format": {
"type": "text"
},
"verbosity": "low"
},
"top_logprobs": 123,
"truncation": "auto",
"usage": {
"input_tokens": 123,
"input_tokens_details": {
"cached_tokens": 123
},
"output_tokens": 123,
"output_tokens_details": {
"reasoning_tokens": 123
},
"total_tokens": 123
},
"user": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
Body
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.
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.
"parallel"
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.
"What are the latest developments in fusion energy?"
System instructions for the model.
ID of a previous response to use as conversation context.
Whether to stream the response.
Configuration for text output, including structured output.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Reasoning configuration. effort (low/medium/high) controls how much research is performed; defaults to medium.
Show child attributes
Show child attributes
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.
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.
- ResponseWebSearchTool
- ResponseMcpTool
- Option 3
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
"response"An assistant message produced by the model.
- ResponseOutputMessage
- ResponseFunctionWebSearch
- ResponseMcpCall
- ResponseMcpListTools
Show child attributes
Show child attributes
Details of a failed response.
Show child attributes
Show child attributes
Details about why the response is incomplete.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
"parallel"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.
- ResponseWebSearchTool
- ResponseMcpTool
Show child attributes
Show child attributes
Moderation results for the response input and output, if moderated completions were requested.
Show child attributes
Show child attributes
in_memory, 24h Reasoning configuration (OpenAI-compatible subset).
Show child attributes
Show child attributes
auto, default, flex, scale, priority completed, failed, in_progress, cancelled, queued, incomplete 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.
Show child attributes
Show child attributes
auto, disabled Estimated token usage, populated for OpenAI SDK compatibility. Counts are approximate; Parallel bills per request, not per token.
Show child attributes
Show child attributes