---
title: "Create Response"
method: POST
path: "/v1/responses"
tags: ["Responses API"]
---

# Create Response

`POST /v1/responses`

## Request

- Base URL: `https://api.parallel.ai`
- URL: `https://api.parallel.ai/v1/responses`
- Auth: API key in header `x-api-key`

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`/`auto`) 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`.

## Request body

- ResponseCreateRequest: 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/auto) rather than changing the model name.
  - `input` union, 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.
    - string
    - ResponseInputMessage[]
      - `role` 'user' | 'assistant' | 'system' | 'developer', required: The role of the message author.
      - `content` union, required: Text content of the message. Either a string or a list of content parts (`{text, type}` objects) for OpenAI SDK clients.
        - string
        - ResponseInputContentPart[]
          - `type` string, nullable: The content part type. Supported: `input_text`, `output_text`, and `text`. Multimodal types (`input_image`, `input_audio`, `input_file`) are rejected with a 422 error.
          - `text` string, nullable: The text payload, when the part carries one.
  - `instructions` string, nullable: System instructions for the model.
  - `previous_response_id` string, nullable: ID of a previous response to use as conversation context.
  - `stream` boolean, nullable: Whether to stream the response.
  - `text` ResponseTextConfig: 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.
    - `format` union
      - ResponseFormatText: Default response format. Used to generate text responses.
        - `type` 'text', required
      - ResponseFormatTextJSONSchemaConfig: JSON Schema output format: the response's output text conforms to `schema`.
        - `name` string, required
        - `schema` object, required
        - `type` 'json_schema', required
        - `description` string, nullable
        - `strict` boolean, nullable
      - ResponseFormatJSONObject: JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.
        - `type` 'json_object', required
    - `verbosity` 'low' | 'medium' | 'high', nullable
  - `metadata` object, nullable: 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: Reasoning configuration (OpenAI-compatible subset).
    - `effort` 'low' | 'medium' | 'high' | 'auto', nullable: Controls how much research is performed, trading response time for answer quality. Defaults to `medium` when omitted. `auto` picks the right effort for each query.
  - `background` boolean, nullable: 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` union[], nullable: 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.
    - union
      - ResponseWebSearchTool: 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.
        - `type` 'web_search' | 'web_search_2025_08_26', required
        - `filters` ResponseWebSearchToolFilters: Domain filters on the OpenAI `web_search` tool, mapped onto Parallel's source policy: `allowed_domains` -> `include_domains`, `blocked_domains` -> `exclude_domains`. Entries follow the Source Policy rules (plain domains match their subdomains; no schemes, ports, query strings or fragments; at most 200 entries in total). Setting both lists is accepted, but only the allow list applies today.
          - `allowed_domains` string[], nullable: Only sources on these domains (and their subdomains) are used. Maps to `source_policy.include_domains`.
          - `blocked_domains` string[], nullable: Sources on these domains (and their subdomains) are excluded. Maps to `source_policy.exclude_domains`. When `allowed_domains` is also set, the allow list is what applies.
        - `search_context_size` 'low' | 'medium' | 'high', nullable
        - `user_location` UserLocation: The approximate location of the user.
          - `city` string, nullable
          - `country` string, nullable
          - `region` string, nullable
          - `timezone` string, nullable
          - `type` 'approximate', nullable
      - ResponseMcpTool: The OpenAI `mcp` tool: a remote MCP server the `parallel` model may call while researching, alongside web search. Each call is reported as an `mcp_call` output item. `headers` and `authorization` are sent to the server and never echoed back. Parallel runs tool calls without an approval round trip, so `require_approval` must be set to `never` explicitly. `connector_id` and `tunnel_id` are not supported.
        - `server_label` string, required: Name for this server. Appears as `server_label` on its `mcp_call` items and must not collide with a `data_sources` partner name.
        - `type` 'mcp', required
        - `allowed_tools` string[], nullable: Tool names the model may call on this server. Omit to allow every tool; an empty list is rejected.
        - `authorization` string, password, nullable: OAuth access token, sent as `Authorization: Bearer <token>`.
        - `headers` object, nullable: HTTP headers sent on every request to the server, for authentication or other purposes.
        - `require_approval` 'never', required: Must be `never`: tool calls run without an approval step.
        - `server_description` string, nullable
        - `server_url` string, required: URL of the MCP server.
      - object
  - `data_sources` TaskDataSources
    - `pay_per_use` string[]: Pay-per-use data partners to enable for this task, in addition to sources included with the processor. See the Data Sources documentation for the available names.
    - `free` string[]: Free data partners to enable for this task, in addition to sources included with the processor. Never billed. See the Data Sources documentation for the available names.

## Response `200`

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.

- Response: 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
  - `error` ResponseError: Details of a failed response.
    - `code` 'server_error', required: Error code; currently always "server_error".
    - `message` string, required
  - `incomplete_details` IncompleteDetails: Details about why the response is incomplete.
    - `reason` 'max_output_tokens' | 'content_filter', nullable
  - `instructions` string, nullable
  - `metadata` object, nullable
  - `model` 'parallel'
  - `object` 'response', required
  - `output` union[], required
    - union
      - ResponseOutputMessage: An assistant message produced by the model.
        - `id` string, required
        - `content` ResponseOutputText[], required
          - `annotations` AnnotationURLCitation[], required
            - `end_index` integer, required
            - `start_index` integer, required
            - `title` string, required
            - `type` 'url_citation', required
            - `url` string, required
          - `text` string, required
          - `type` 'output_text', required
          - `logprobs` OpenaiTypesResponsesResponseOutputTextLogprob[], nullable
            - `token` string, required
            - `bytes` integer[], required
            - `logprob` number, required
            - `top_logprobs` OpenaiTypesResponsesResponseOutputTextLogprobTopLogprob[], required
              - …
        - `role` 'assistant', required
        - `status` 'in_progress' | 'completed' | 'incomplete', required
        - `type` 'message', required
        - `phase` 'commentary' | 'final_answer', nullable
      - ResponseFunctionWebSearch: One web action the `parallel` model took while researching the answer: a `search` (`action.queries` are the search queries issued, `action.query` the first of them) or an `open_page` (`action.url` is the page it read).
        - `id` string, required
        - `action` union, required
          - ActionSearch: Action type "search" - Performs a web search query.
            - `type` 'search', required
            - `queries` string[], nullable
            - `query` string, nullable
            - `sources` ActionSearchSource[], nullable
              - …
          - ActionOpenPage: Action type "open_page" - Opens a specific URL from search results.
            - `type` 'open_page', required
            - `url` string, nullable
        - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required
        - `type` 'web_search_call', required
      - ResponseMcpCall: One tool call the `parallel` model made on an MCP server: a server from the request's `mcp` tools, or a partner enabled via `data_sources`. `arguments` is the JSON-encoded input; `output` is the text the tool returned, or `error` the failure when the call did not succeed.
        - `id` string, required
        - `arguments` string, required
        - `name` string, required
        - `server_label` string, required
        - `type` 'mcp_call', required
        - `error` union
          - ResponseMcpToolExecutionError
            - `type` 'mcp_tool_execution_error'
            - `content` unknown, required
          - ResponseMcpProtocolError
            - `type` 'mcp_protocol_error'
            - `code` integer, required
            - `message` string, required
          - ResponseMcpHttpError
            - `type` 'http_error'
            - `code` integer, required
            - `message` string, required
        - `output` string, nullable
        - `status` 'completed' | 'failed', required
      - ResponseMcpListTools: Tools discovered on a customer MCP server, or a connection/listing error. Requested data partners report failures only, with an empty tools list.
        - `id` string, required
        - `server_label` string, required
        - `tools` McpListToolsTool[], required
          - `input_schema` unknown, required
          - `name` string, required
          - `annotations` unknown
          - `description` string, nullable
        - `type` 'mcp_list_tools', required
        - `error` string, nullable
  - `parallel_tool_calls` boolean, required
  - `temperature` number, nullable
  - `tool_choice` string
  - `tools` union[]
    - union
      - ResponseWebSearchTool: 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.
        - `type` 'web_search' | 'web_search_2025_08_26', required
        - `filters` ResponseWebSearchToolFilters: Domain filters on the OpenAI `web_search` tool, mapped onto Parallel's source policy: `allowed_domains` -> `include_domains`, `blocked_domains` -> `exclude_domains`. Entries follow the Source Policy rules (plain domains match their subdomains; no schemes, ports, query strings or fragments; at most 200 entries in total). Setting both lists is accepted, but only the allow list applies today.
          - `allowed_domains` string[], nullable: Only sources on these domains (and their subdomains) are used. Maps to `source_policy.include_domains`.
          - `blocked_domains` string[], nullable: Sources on these domains (and their subdomains) are excluded. Maps to `source_policy.exclude_domains`. When `allowed_domains` is also set, the allow list is what applies.
        - `search_context_size` 'low' | 'medium' | 'high', nullable
        - `user_location` UserLocation: The approximate location of the user.
          - `city` string, nullable
          - `country` string, nullable
          - `region` string, nullable
          - `timezone` string, nullable
          - `type` 'approximate', nullable
      - ResponseMcpTool: The OpenAI `mcp` tool: a remote MCP server the `parallel` model may call while researching, alongside web search. Each call is reported as an `mcp_call` output item. `headers` and `authorization` are sent to the server and never echoed back. Parallel runs tool calls without an approval round trip, so `require_approval` must be set to `never` explicitly. `connector_id` and `tunnel_id` are not supported.
        - `server_label` string, required: Name for this server. Appears as `server_label` on its `mcp_call` items and must not collide with a `data_sources` partner name.
        - `type` 'mcp', required
        - `allowed_tools` string[], nullable: Tool names the model may call on this server. Omit to allow every tool; an empty list is rejected.
        - `authorization` string, password, nullable: OAuth access token, sent as `Authorization: Bearer <token>`.
        - `headers` object, nullable: HTTP headers sent on every request to the server, for authentication or other purposes.
        - `require_approval` 'never', required: Must be `never`: tool calls run without an approval step.
        - `server_description` string, nullable
        - `server_url` string, required: URL of the MCP server.
  - `top_p` number, nullable
  - `background` boolean, nullable
  - `completed_at` number, nullable
  - `conversation` unknown
  - `max_output_tokens` integer, nullable
  - `max_tool_calls` integer, nullable
  - `moderation` Moderation: Moderation results for the response input and output, if moderated completions were requested.
    - `input` union, required
      - ModerationInputModerationResult: A moderation result produced for the response input or output.
        - `categories` object, required
        - `category_applied_input_types` object, required
        - `category_scores` object, required
        - `flagged` boolean, required
        - `model` string, required
        - `type` 'moderation_result', required
      - ModerationInputError: An error produced while attempting moderation for the response input or output.
        - `code` string, required
        - `message` string, required
        - `type` 'error', required
    - `output` union, required
      - ModerationOutputModerationResult: A moderation result produced for the response input or output.
        - `categories` object, required
        - `category_applied_input_types` object, required
        - `category_scores` object, required
        - `flagged` boolean, required
        - `model` string, required
        - `type` 'moderation_result', required
      - ModerationOutputError: An error produced while attempting moderation for the response input or output.
        - `code` string, required
        - `message` string, required
        - `type` 'error', required
  - `previous_response_id` string, nullable
  - `prompt` unknown
  - `prompt_cache_key` string, nullable
  - `prompt_cache_retention` 'in_memory' | '24h', nullable
  - `reasoning` ResponseReasoningConfig: Reasoning configuration (OpenAI-compatible subset).
    - `effort` 'low' | 'medium' | 'high' | 'auto', nullable: Controls how much research is performed, trading response time for answer quality. Defaults to `medium` when omitted. `auto` picks the right effort for each query.
  - `safety_identifier` string, nullable
  - `service_tier` 'auto' | 'default' | 'flex' | 'scale' | 'priority', nullable
  - `status` 'completed' | 'failed' | 'in_progress' | 'cancelled' | 'queued' | 'incomplete', nullable
  - `text` ResponseTextConfig: 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.
    - `format` union
      - ResponseFormatText: Default response format. Used to generate text responses.
        - `type` 'text', required
      - ResponseFormatTextJSONSchemaConfig: JSON Schema output format: the response's output text conforms to `schema`.
        - `name` string, required
        - `schema` object, required
        - `type` 'json_schema', required
        - `description` string, nullable
        - `strict` boolean, nullable
      - ResponseFormatJSONObject: JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.
        - `type` 'json_object', required
    - `verbosity` 'low' | 'medium' | 'high', nullable
  - `top_logprobs` integer, nullable
  - `truncation` 'auto' | 'disabled', nullable
  - `usage` ResponseUsage: Estimated token usage, populated for OpenAI SDK compatibility. Counts are approximate; Parallel bills per request, not per token.
    - `input_tokens` integer, required
    - `input_tokens_details` InputTokensDetails, required: A detailed breakdown of the input tokens.
      - `cached_tokens` integer, required
    - `output_tokens` integer, required
    - `output_tokens_details` OutputTokensDetails, required: A detailed breakdown of the output tokens.
      - `reasoning_tokens` integer, required
    - `total_tokens` integer, required
  - `user` string, nullable
  - `effort_used` 'low' | 'medium' | 'high', nullable: The effort this response was served and billed at. For `auto`, the effort it picked for this query (either `low` or `medium`). Null until the response completes.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-22** `c4ae7c37e089`: 6 warning, 7 info
  - added the new `auto` enum value to the `anyOf[subschema #17: ResponseCompletedEvent]/response/reasoning/anyOf[subschema #1: ResponseReasoningConfig]/effort/anyOf[subschema #1]/` response property for the response status `200` (media type: text/event-stream)
  - added the new `auto` enum value to the `anyOf[subschema #18: ResponseFailedEvent]/response/reasoning/anyOf[subschema #1: ResponseReasoningConfig]/effort/anyOf[subschema #1]/` response property for the response status `200` (media type: text/event-stream)
  - added the new `auto` enum value to the `anyOf[subschema #19: ResponseIncompleteEvent]/response/reasoning/anyOf[subschema #1: ResponseReasoningConfig]/effort/anyOf[subschema #1]/` response property for the response status `200` (media type: text/event-stream)
  - added the new `auto` enum value to the `anyOf[subschema #1: ResponseCreatedEvent]/response/reasoning/anyOf[subschema #1: ResponseReasoningConfig]/effort/anyOf[subschema #1]/` response property for the response status `200` (media type: text/event-stream)
  - …9 more
- **2026-10-16** `fc4858951ccf`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1/responses/post.md)

---

[API](https://skmtc.dev/parallel-web/apis/parallel-api.md) - [All operations](https://skmtc.dev/parallel-web/apis/parallel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parallel-web/apis/parallel-api/revisions/eae6def9641f?raw)