Responses API Objects

Type definitions for every object the Responses API emits — Response, OutputItem, ContentPart, ContentFilter, ResponsesStreamEvent, ResponsesUsage.

This page defines every named object returned by POST /v1/responses. Reference these from guides and other docs:

"Returns a Response object."

The `Response` Object

The top-level object returned by a non-streaming POST /v1/responses call, and also embedded in the response.completed stream event.

interface Response {
  id:                  string;
  object:              "response";
  created_at:          number;
  model:               string;
  status:              "in_progress" | "completed" | "cancelled" | "failed";
  instructions:        string | null;
  store:               boolean;
  parallel_tool_calls: boolean;
  output:              OutputItem[];
  tools:               Tool[];
  tool_choice:         string | object;
  truncation:          "auto" | "disabled";
  usage:               ResponsesUsage | null;
  metadata:            Record<string, string>;
  error:               ResponseError | null;
  content_filters:     ContentFilter[] | null;
  previous_response_id: string | null;
  temperature:         number;
  top_p:               number;
  frequency_penalty:   number;
  presence_penalty:    number;
  max_output_tokens:   number | null;
  service_tier:        string;
}

Field	Type	Description
`id`	`string`	Unique response ID (`resp_...`). Pass to `previous_response_id` on the next turn
`object`	`"response"`	Type discriminator
`created_at`	`number`	Unix timestamp of when the response was created
`model`	`string`	Resolved model identifier
`status`	`string`	Lifecycle status — see values below
`instructions`	`string \| null`	System instructions, if any
`store`	`boolean`	Whether the response is persisted server-side
`output`	`OutputItem[]`	Ordered list of items the model produced
`content_filters`	`ContentFilter[]`	Safety evaluation for prompt and completion. `null` mid-stream
`previous_response_id`	`string \| null`	ID of the prior response in a multi-turn chain
`usage`	`ResponsesUsage`	Token counts. Present when `status` is `"completed"`
`error`	`ResponseError \| null`	Set when `status` is `"failed"`

status values:

Value	Meaning
`"in_progress"`	Generation is ongoing (only seen mid-stream)
`"completed"`	The model finished naturally
`"cancelled"`	The response was cancelled (e.g., stream disconnect)
`"failed"`	An error occurred — see `error` field

The `OutputItem` Object

A single item produced by the model within a response. Output items form the output[] array of a Response.

type OutputItem =
  | MessageOutputItem
  | FunctionCallOutputItem
  | ReasoningOutputItem;

interface MessageOutputItem {
  type:    "message";
  id:      string;
  role:    "assistant";
  status:  "in_progress" | "completed";
  content: ContentPart[];
}

interface FunctionCallOutputItem {
  type:       "function_call";
  id:         string;
  call_id:    string;
  name:       string;
  arguments:  string;   // JSON string — parse with JSON.parse()
  status:     "in_progress" | "completed";
}

interface ReasoningOutputItem {
  type:    "reasoning";
  id:      string;
  summary: ReasoningSummary[];
  status:  "in_progress" | "completed";
}

Field	Type	Description
`type`	`string`	`"message"`, `"function_call"`, or `"reasoning"`
`id`	`string`	Unique item ID within the response
`role`	`"assistant"`	Present on `message` items
`content`	`ContentPart[]`	Content parts within a `message` item
`call_id`	`string`	Present on `function_call` items — reference this when submitting tool results
`name`	`string`	Tool name for `function_call` items
`arguments`	`string`	JSON-encoded arguments for `function_call` items
`status`	`string`	`"in_progress"` mid-stream, `"completed"` when finalized

The `ContentPart` Object

A content part within a message OutputItem.

type ContentPart =
  | OutputTextContent
  | RefusalContent;

interface OutputTextContent {
  type:        "output_text";
  text:        string;
  annotations: Annotation[];
}

interface RefusalContent {
  type:    "refusal";
  refusal: string;
}

Field	Type	Description
`type`	`string`	`"output_text"` for generated text, `"refusal"` if the model declined
`text`	`string`	The generated text (for `output_text` type)
`annotations`	`Annotation[]`	Citations or link annotations embedded in the text
`refusal`	`string`	The refusal message (for `refusal` type)

The `ContentFilter` Object

Skytells safety evaluation attached to the content_filters[] array on every Response. Each entry covers one source — either the prompt or the completion.

interface ContentFilter {
  blocked:               boolean;
  source_type:           "prompt" | "completion";
  content_filter_raw:    unknown[];
  content_filter_results: {
    hate?:                   { filtered: boolean; severity: string };
    sexual?:                 { filtered: boolean; severity: string };
    violence?:               { filtered: boolean; severity: string };
    self_harm?:              { filtered: boolean; severity: string };
    jailbreak?:              { detected: boolean; filtered: boolean };
    protected_material_code?: { detected: boolean; filtered: boolean };
    protected_material_text?: { detected: boolean; filtered: boolean };
  };
  content_filter_offsets: {
    start_offset: number;
    end_offset:   number;
    check_offset: number;
  };
}

Field	Type	Description
`blocked`	`boolean`	`true` if this source triggered a safety block
`source_type`	`string`	`"prompt"` for the input; `"completion"` for the generated output
`content_filter_results`	`object`	Per-category safety scores. Prompt entries include `jailbreak`; completion entries include `protected_material_code` / `protected_material_text`
`content_filter_offsets`	`object`	Byte offsets within the source text that were evaluated

When a response is blocked, blocked: true is set on the relevant entry and the Response will have status: "failed" with an error field.

The `ResponsesStreamEvent` Object

A discriminated union of all Server-Sent Event types emitted by a streaming POST /v1/responses call. Each event has a type field identifying its shape.

type ResponsesStreamEvent =
  | ResponseCreatedEvent
  | ResponseInProgressEvent
  | ResponseOutputItemAddedEvent
  | ResponseContentPartAddedEvent
  | ResponseOutputTextDeltaEvent
  | ResponseOutputTextAnnotationAddedEvent
  | ResponseOutputTextDoneEvent
  | ResponseContentPartDoneEvent
  | ResponseOutputItemDoneEvent
  | ResponseCompletedEvent
  | ResponseFailedEvent
  | ResponseCancelledEvent;

`response.created`

interface ResponseCreatedEvent {
  type:     "response.created";
  response: Response;  // status: "in_progress"
}

Emitted immediately when the server acknowledges the request. Contains the initial Response stub (no output yet).

`response.in_progress`

interface ResponseInProgressEvent {
  type:     "response.in_progress";
  response: Response;
}

Periodic heartbeat while generation is running.

`response.output_item.added`

interface ResponseOutputItemAddedEvent {
  type:         "response.output_item.added";
  output_index: number;
  item:         OutputItem;  // status: "in_progress"
}

A new OutputItem has started being generated.

`response.content_part.added`

interface ResponseContentPartAddedEvent {
  type:          "response.content_part.added";
  item_id:       string;
  output_index:  number;
  content_index: number;
  part:          ContentPart;
}

A new ContentPart within an output item has started.

`response.output_text.delta`

interface ResponseOutputTextDeltaEvent {
  type:          "response.output_text.delta";
  item_id:       string;
  output_index:  number;
  content_index: number;
  delta:         string;   // incremental text token(s) — concatenate to reconstruct
}

An incremental text chunk. Concatenate all delta values across events to reconstruct the full output text.

`response.output_text.annotation.added`

interface ResponseOutputTextAnnotationAddedEvent {
  type:             "response.output_text.annotation.added";
  item_id:          string;
  output_index:     number;
  content_index:    number;
  annotation_index: number;
  annotation:       Annotation;
}

A citation or link annotation was attached to the current text content part.

`response.output_text.done`

interface ResponseOutputTextDoneEvent {
  type:          "response.output_text.done";
  item_id:       string;
  output_index:  number;
  content_index: number;
  text:          string;   // complete final text of this content part
}

The text content part is finalized. text contains the full assembled string.

`response.content_part.done`

interface ResponseContentPartDoneEvent {
  type:          "response.content_part.done";
  item_id:       string;
  output_index:  number;
  content_index: number;
  part:          ContentPart;
}

A content part within an output item is complete.

`response.output_item.done`

interface ResponseOutputItemDoneEvent {
  type:         "response.output_item.done";
  output_index: number;
  item:         OutputItem;  // status: "completed"
}

An OutputItem is fully emitted.

`response.completed`

interface ResponseCompletedEvent {
  type:     "response.completed";
  response: Response;  // status: "completed", includes usage
}

The stream is done. The full Response object is attached, including usage totals.

`response.failed`

interface ResponseFailedEvent {
  type:     "response.failed";
  response: Response;  // status: "failed", error field populated
}

`response.cancelled`

interface ResponseCancelledEvent {
  type:     "response.cancelled";
  response: Response;  // status: "cancelled"
}

The `ResponsesUsage` Object

Token consumption for a Response.

interface ResponsesUsage {
  input_tokens:   number;
  output_tokens:  number;
  total_tokens:   number;
  input_token_details: {
    cached_tokens: number;
  };
  output_token_details: {
    reasoning_tokens: number;
  };
}

Field	Type	Description
`input_tokens`	`number`	Tokens in the input (all turns for multi-turn, but only new tokens are counted as billable)
`output_tokens`	`number`	Tokens generated by the model this turn
`total_tokens`	`number`	Sum of `input_tokens` + `output_tokens`
`input_token_details.cached_tokens`	`number`	Input tokens served from the server-side conversation cache (not re-processed)
`output_token_details.reasoning_tokens`	`number`	Internal chain-of-thought tokens used by reasoning models

How is this guide?

On this page