Responses

The Responses API is compatible with the OpenAI Responses API. It allows you to create stateful model interactions where each response can reference previous ones via an ID. Portkey proxies these requests to the configured provider.

The Responses API is currently supported for providers that implement the OpenAI Responses API contract. Check your provider’s documentation to confirm compatibility.

Create a model response

POST /v1/responses Creates a new model response. The request body is forwarded to the provider.

Request

string

required

The provider to route the request to (e.g. openai).

string

required

Your Portkey API key or provider API key.

string

required

The model to use for the response (e.g. gpt-4o).

string | array

required

The input for the model. Can be a plain text string or an array of message objects.

string

The ID of a previous response to continue from. Enables multi-turn stateful conversations.

string

System-level instructions to guide the model’s behavior.

array

A list of tools the model may call. Follows the OpenAI tool definition format.

boolean

default:"false"

Whether to stream the response. When true, the gateway returns server-sent events.

number

Maximum number of tokens in the output.

Response

string

Unique identifier for the response.

string

Always response.

string

The model that generated the response.

string

Response status. Values: completed, in_progress, failed, cancelled.

array

Array of output items generated by the model.

object

Show properties

number

Number of tokens in the input.

number

Number of tokens in the output.

number

Total tokens used.

curl https://your-gateway.example.com/v1/responses \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai" \
  -d '{
    "model": "gpt-4o",
    "input": "Explain quantum entanglement in simple terms."
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://your-gateway.example.com/v1",
    api_key="YOUR_API_KEY",
    default_headers={
        "x-portkey-provider": "openai",
    },
)

response = client.responses.create(
    model="gpt-4o",
    input="Explain quantum entanglement in simple terms.",
)

print(response.id, response.status)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://your-gateway.example.com/v1",
  apiKey: "YOUR_API_KEY",
  defaultHeaders: {
    "x-portkey-provider": "openai",
  },
});

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Explain quantum entanglement in simple terms.",
});

console.log(response.id, response.status);

Get a response

GET /v1/responses/:id Retrieves a previously created model response by its ID.

Request

string

required

The ID of the response to retrieve.

string

required

The provider to route the request to.

string

required

Your Portkey API key or provider API key.

Response

Returns the response object. See Create a model response for the full field list.

curl https://your-gateway.example.com/v1/responses/resp-abc123 \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

response = client.responses.retrieve("resp-abc123")
print(response.status)

const response = await client.responses.retrieve("resp-abc123");
console.log(response.status);

Delete a response

DELETE /v1/responses/:id Deletes a stored model response.

Deletion is permanent. Any response chain built on top of this response via previous_response_id may become incomplete.

Request

string

required

The ID of the response to delete.

string

required

The provider to route the request to.

string

required

Your Portkey API key or provider API key.

Response

string

The ID of the deleted response.

string

Always response.

boolean

true if the response was successfully deleted.

curl https://your-gateway.example.com/v1/responses/resp-abc123 \
  -X DELETE \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

result = client.responses.delete("resp-abc123")
print(result.deleted)

const result = await client.responses.delete("resp-abc123");
console.log(result.deleted);

List response input items

GET /v1/responses/:id/input_items Returns the input items that were included in a response. This is useful for inspecting the full context that was sent to the model.

Request

string

required

The ID of the response whose input items to list.

string

required

The provider to route the request to.

string

required

Your Portkey API key or provider API key.

number

default:"20"

Maximum number of input items to return.

string

Cursor for pagination.

Response

string

Always list.

array

Array of input item objects representing the messages and context sent in the request.

boolean

Whether additional input items are available.

curl https://your-gateway.example.com/v1/responses/resp-abc123/input_items \
  -H "x-portkey-api-key: YOUR_API_KEY" \
  -H "x-portkey-provider: openai"

items = client.responses.input_items.list("resp-abc123")
for item in items.data:
    print(item)

const items = await client.responses.inputItems.list("resp-abc123");
for (const item of items.data) {
  console.log(item);
}

Overview

Chat

Multimodal

Files & Batches

Other

Create a model response

Request

Response

Get a response

Request

Response

Delete a response

Request

Response

List response input items

Request

Response

​Create a model response

​Request

​Response

​Get a response

​Request

​Response

​Delete a response

​Request

​Response

​List response input items

​Request

​Response

Create a model response

Request

Response

Get a response

Request

Response

Delete a response

Request

Response

List response input items

Request

Response