Responses Types

TypeScript types for the Responses API, including reasoning control and multi-turn conversations.

API Documentation Reference: Responses types conform to the POST /v1/responses API. The SDK provides TypeScript types that match the API exactly.

See Responses for usage.

ResponsesCreateParams

interface ResponsesCreateParams {
  model: string;
  input: string | ResponsesInputMessage[];
  instructions?: string | null;
  stream?: boolean | null;
  temperature?: number;
  top_p?: number;
  max_output_tokens?: number | null;
  tools?: ChatCompletionTool[];
  tool_choice?: ChatCompletionToolChoiceOption;
  parallel_tool_calls?: boolean;
  reasoning?: {
    effort?: 'none' | 'low' | 'medium' | 'high';
    summary?: 'auto' | 'concise' | 'detailed';
  };
  text?: {
    format?: unknown;
    verbosity?: unknown;
  };
  store?: boolean;
  previous_response_id?: string | null;
  metadata?: Record<string, unknown>;
  user?: string | null;
  truncation?: string;
  frequency_penalty?: number;
  presence_penalty?: number;
}

Parameter	Type	Description
`model`	`string`	Model slug.
`input`	`string \| ResponsesInputMessage[]`	Prompt or messages.
`instructions`	`string`	System-level instructions.
`stream`	`boolean`	`true` for SSE streaming.
`temperature`	`number`	Sampling temperature.
`top_p`	`number`	Nucleus sampling.
`max_output_tokens`	`number`	Maximum output tokens.
`tools`	`ChatCompletionTool[]`	Tool definitions.
`tool_choice`	`ChatCompletionToolChoiceOption`	Tool invocation mode.
`parallel_tool_calls`	`boolean`	Allow parallel calls.
`reasoning`	`{ effort?, summary? }`	Reasoning control. `effort`: `'none'` · `'low'` · `'medium'` · `'high'`. `summary`: `'auto'` · `'concise'` · `'detailed'`.
`text`	`{ format?, verbosity? }`	Output formatting options.
`store`	`boolean`	Persist server-side for multi-turn.
`previous_response_id`	`string`	Chain to a prior response.
`metadata`	`Record<string, unknown>`	Arbitrary labels.
`user`	`string`	End-user identifier.
`truncation`	`string`	`'auto'` or `'disabled'`.
`frequency_penalty`	`number`	Frequency penalty.
`presence_penalty`	`number`	Presence penalty.

ResponsesResponse

Returned by client.responses.create() from POST /v1/responses. This TypeScript interface matches the API JSON response exactly — the SDK performs no transformations.

interface ResponsesResponse {
  id: string;
  object: 'response';
  created_at: number;
  status: string;
  model: string;
  output: ResponsesOutputMessage[];
  usage: ResponsesUsage;
  content_filters: ResponsesContentFilter[];
  instructions: string | null;
  previous_response_id: string | null;
  reasoning: object;
  store: boolean;
  metadata: Record<string, unknown>;
}

Field	Type	Description
`id`	`string`	Response ID (chainable via `previous_response_id`).
`object`	`'response'`	Object type.
`created_at`	`number`	Unix timestamp.
`status`	`string`	`'completed'` · `'in_progress'` · `'failed'`.
`model`	`string`	Model used.
`output`	`ResponsesOutputMessage[]`	Output messages.
`usage`	`ResponsesUsage`	Token counts with details.
`content_filters`	`ResponsesContentFilter[]`	Safety filter results. See Safety.
`instructions`	`string`	System instructions used.
`previous_response_id`	`string`	Parent response.
`reasoning`	`object`	Applied reasoning settings.
`store`	`boolean`	Whether persisted.
`metadata`	`Record<string, unknown>`	User metadata.

ResponsesInputMessage

interface ResponsesInputMessage {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string | ContentPart[];
  name?: string;
  tool_call_id?: string;
}

Field	Type	Description
`role`	`'system' \| 'user' \| 'assistant' \| 'tool'`	Message role.
`content`	`string \| ContentPart[]`	Text or multi-part.
`name`	`string`	Optional name.
`tool_call_id`	`string`	Tool call ID (for `role: 'tool'`).

ResponsesOutputMessage

interface ResponsesOutputMessage {
  id: string;
  type: string;
  status: string;
  role: string;
  content: ResponsesOutputContent[];
}

Field	Type	Description
`id`	`string`	Message ID.
`type`	`string`	Message type.
`status`	`string`	Message status.
`role`	`string`	Role.
`content`	`ResponsesOutputContent[]`	Content parts.

ResponsesUsage

interface ResponsesUsage {
  input_tokens: number;
  output_tokens: number;
  total_tokens: number;
  input_tokens_details: { cached_tokens?: number };
  output_tokens_details: { reasoning_tokens?: number };
}

Field	Type	Description
`input_tokens`	`number`	Input tokens.
`output_tokens`	`number`	Output tokens.
`total_tokens`	`number`	Total tokens.
`input_tokens_details`	`{ cached_tokens? }`	Cached token details.
`output_tokens_details`	`{ reasoning_tokens? }`	Reasoning token details.

ResponsesContentFilter

interface ResponsesContentFilter {
  blocked: boolean;
  source_type: 'prompt' | 'completion';
  content_filter_results: object;
}

Field	Type	Description
`blocked`	`boolean`	Whether content was blocked.
`source_type`	`'prompt' \| 'completion'`	Filter source.
`content_filter_results`	`object`	Per-category results (`hate`, `sexual`, `violence`, `self_harm`, `jailbreak`, etc.).

Streaming Events

type ResponsesStreamEvent =
  | ResponsesCreatedEvent         // type: 'response.created'
  | ResponsesInProgressEvent      // type: 'response.in_progress'
  | ResponsesCompletedEvent       // type: 'response.completed'
  | ResponsesOutputItemAddedEvent // type: 'response.output_item.added'
  | ResponsesOutputItemDoneEvent  // type: 'response.output_item.done'
  | ResponsesContentPartAddedEvent// type: 'response.content_part.added'
  | ResponsesContentPartDoneEvent // type: 'response.content_part.done'
  | ResponsesOutputTextDeltaEvent // type: 'response.output_text.delta'
  | ResponsesOutputTextDoneEvent  // type: 'response.output_text.done'

ResponsesStreamEvent is a discriminated union on type. See Streaming Events. Each event extends ResponsesEventBase with sequence_number: number.

Key Events

Event	Fields	Description
`ResponsesOutputTextDeltaEvent`	`output_index`, `content_index`, `item_id`, `delta`	Incremental text.
`ResponsesOutputTextDoneEvent`	`output_index`, `content_index`, `item_id`, `text`	Full accumulated text.
`ResponsesCompletedEvent`	`response`	Full `ResponsesResponse` with `usage`.

SDK Responses — Complete responses implementation guide
Responses API — API documentation for responses
SDK Safety — Content filtering with wasFiltered()

How is this guide?

On this page