Running Assistants

POST /v1/threads/{thread_id}/runs

Python

from openai import OpenAI
client = OpenAI()

# Create and run
run = client.beta.threads.runs.create(
    thread_id="thread_abc123",
    assistant_id="asst_abc123"
)

print(run.id, run.status)

# Retrieve run status
run = client.beta.threads.runs.retrieve(
    thread_id="thread_abc123",
    run_id=run.id
)

print(run.status)

import OpenAI from "openai";
const openai = new OpenAI();

// Create and run
let run = await openai.beta.threads.runs.create(
  "thread_abc123",
  {
    assistant_id: "asst_abc123"
  }
);

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

// Retrieve run status
run = await openai.beta.threads.runs.retrieve(
  "thread_abc123",
  run.id
);

console.log(run.status);

curl https://api.openai.com/v1/threads/thread_abc123/runs \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -H "OpenAI-Beta: assistants=v2" \\
  -d '{
    "assistant_id": "asst_abc123"
  }'

{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699063290,
  "thread_id": "thread_abc123",
  "assistant_id": "asst_abc123",
  "status": "queued",
  "started_at": 1699063290,
  "model": "gpt-4o",
  "instructions": "You are a personal math tutor.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000
}

The Assistants API is deprecated in favor of the Responses API.

Create a run to execute an assistant on a thread.

Path Parameters

thread_id · string · required

The ID of the thread to run.

Request Body

assistant_id · string · required

The ID of the assistant to use to execute this run.

model · string

The ID of the Model to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used.

instructions · string

Overrides the instructions of the assistant. This is useful for modifying the behavior on a per-run basis.

additional_instructions · string

Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions.

additional_messages · array

Adds additional messages to the thread before creating the run.

tools · array

Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis.

metadata · object

Set of 16 key-value pairs that can be attached to an object.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

temperature · number

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

max_prompt_tokens · integer

The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status incomplete.

max_completion_tokens · integer

The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status incomplete.

stream · boolean

If true, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a data: [DONE] message.

Response

Returns a Run object.

id · string

The run identifier.

object · string

The object type, always thread.run.

created_at · integer

The Unix timestamp (in seconds) for when the run was created.

thread_id · string

The ID of the thread that was executed on as a part of this run.

assistant_id · string

The ID of the assistant used for execution of this run.

status · string

The status of the run. One of:

• queued
• in_progress
• requires_action
• cancelling
• cancelled
• failed
• completed
• expired

model · string

The model that the assistant used for this run.

instructions · string

The instructions that the assistant used for this run.

Retrieve Run

GET https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

Retrieves a run.

List Runs

GET https://api.openai.com/v1/threads/{thread_id}/runs

Returns a list of runs belonging to a thread.

Cancel Run

POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/cancel

Cancels a run that is in_progress.

Python

from openai import OpenAI
client = OpenAI()

# Create and run
run = client.beta.threads.runs.create(
    thread_id="thread_abc123",
    assistant_id="asst_abc123"
)

print(run.id, run.status)

# Retrieve run status
run = client.beta.threads.runs.retrieve(
    thread_id="thread_abc123",
    run_id=run.id
)

print(run.status)

import OpenAI from "openai";
const openai = new OpenAI();

// Create and run
let run = await openai.beta.threads.runs.create(
  "thread_abc123",
  {
    assistant_id: "asst_abc123"
  }
);

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

// Retrieve run status
run = await openai.beta.threads.runs.retrieve(
  "thread_abc123",
  run.id
);

console.log(run.status);

curl https://api.openai.com/v1/threads/thread_abc123/runs \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -H "OpenAI-Beta: assistants=v2" \\
  -d '{
    "assistant_id": "asst_abc123"
  }'

{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699063290,
  "thread_id": "thread_abc123",
  "assistant_id": "asst_abc123",
  "status": "queued",
  "started_at": 1699063290,
  "model": "gpt-4o",
  "instructions": "You are a personal math tutor.",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000
}