openapi: 3.0.0
info:
title: OpenAI Assistants Threads API
description: The Assistants API allows you to build AI assistants within your own applications. An Assistant has instructions and can leverage models, tools, and knowledge to respond to user queries. The Assistants API currently supports three types of tools - Code Interpreter, Retrieval, and Function calling. In the future, we plan to release more OpenAI-built tools, and allow you to provide your own tools on our platform.
version: 2.0.0
termsOfService: https://openai.com/policies/terms-of-use
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Threads
paths:
/threads/{thread_id}/messages/{message_id}/files:
get:
operationId: listMessageFiles
tags:
- Threads
summary: OpenAI Returns a list of message files.
parameters:
- name: thread_id
in: path
description: The ID of the thread that the message and files belong to.
required: true
schema:
type: string
- name: message_id
in: path
description: The ID of the message that the files belongs to.
required: true
schema:
type: string
- name: limit
in: query
description: 'A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
'
required: false
schema:
type: integer
default: 20
- name: order
in: query
description: 'Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
'
schema:
type: string
default: desc
enum:
- asc
- desc
- name: after
in: query
description: 'A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
'
schema:
type: string
- name: before
in: query
description: 'A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessageFilesResponse'
x-oaiMeta:
name: List message files
group: threads
beta: true
returns: A list of [message file](/docs/api-reference/messages/file-object) objects.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmessage_files = client.beta.threads.messages.files.list(\n thread_id=\"thread_abc123\",\n message_id=\"msg_abc123\"\n)\nprint(message_files)\n"
node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const messageFiles = await openai.beta.threads.messages.files.list(\n \"thread_abc123\",\n \"msg_abc123\"\n );\n console.log(messageFiles);\n}\n\nmain();\n"
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"file-abc123\",\n \"object\": \"thread.message.file\",\n \"created_at\": 1699061776,\n \"message_id\": \"msg_abc123\"\n },\n {\n \"id\": \"file-abc123\",\n \"object\": \"thread.message.file\",\n \"created_at\": 1699061776,\n \"message_id\": \"msg_abc123\"\n }\n ],\n \"first_id\": \"file-abc123\",\n \"last_id\": \"file-abc123\",\n \"has_more\": false\n}\n"
/threads/{thread_id}/messages/{message_id}/files/{file_id}:
get:
operationId: getMessageFile
tags:
- Threads
summary: OpenAI Retrieves a message file.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
example: thread_abc123
description: The ID of the thread to which the message and File belong.
- in: path
name: message_id
required: true
schema:
type: string
example: msg_abc123
description: The ID of the message the file belongs to.
- in: path
name: file_id
required: true
schema:
type: string
example: file-abc123
description: The ID of the file being retrieved.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessageFileObject'
x-oaiMeta:
name: Retrieve message file
group: threads
beta: true
returns: The [message file](/docs/api-reference/messages/file-object) object.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123/files/file-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmessage_files = client.beta.threads.messages.files.retrieve(\n thread_id=\"thread_abc123\",\n message_id=\"msg_abc123\",\n file_id=\"file-abc123\"\n)\nprint(message_files)\n"
node.js: "import OpenAI from \"openai\";\nconst openai = new OpenAI();\n\nasync function main() {\n const messageFile = await openai.beta.threads.messages.files.retrieve(\n \"thread_abc123\",\n \"msg_abc123\",\n \"file-abc123\"\n );\n console.log(messageFile);\n}\n\nmain();\n"
response: "{\n \"id\": \"file-abc123\",\n \"object\": \"thread.message.file\",\n \"created_at\": 1699061776,\n \"message_id\": \"msg_abc123\"\n}\n"
/threads:
post:
operationId: createThread
tags:
- Threads
summary: OpenAI Create a thread.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ThreadObject'
x-oaiMeta:
name: Create thread
group: threads
beta: true
returns: A [thread](/docs/api-reference/threads) object.
examples:
- title: Empty
request:
curl: "curl https://api.openai.com/v1/threads \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d ''\n"
python: 'from openai import OpenAI
client = OpenAI()
empty_thread = client.beta.threads.create()
print(empty_thread)
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const emptyThread = await openai.beta.threads.create();\n\n console.log(emptyThread);\n}\n\nmain();"
response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1699012949,\n \"metadata\": {}\n}\n"
- title: Messages
request:
curl: "curl https://api.openai.com/v1/threads \\\n-H \"Content-Type: application/json\" \\\n-H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n-H \"OpenAI-Beta: assistants=v1\" \\\n-d '{\n \"messages\": [{\n \"role\": \"user\",\n \"content\": \"Hello, what is AI?\",\n \"file_ids\": [\"file-abc123\"]\n }, {\n \"role\": \"user\",\n \"content\": \"How does AI work? Explain it in simple terms.\"\n }]\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmessage_thread = client.beta.threads.create(\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"Hello, what is AI?\",\n \"file_ids\": [\"file-abc123\"],\n },\n {\n \"role\": \"user\",\n \"content\": \"How does AI work? Explain it in simple terms.\"\n },\n ]\n)\n\nprint(message_thread)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const messageThread = await openai.beta.threads.create({\n messages: [\n {\n role: \"user\",\n content: \"Hello, what is AI?\",\n file_ids: [\"file-abc123\"],\n },\n {\n role: \"user\",\n content: \"How does AI work? Explain it in simple terms.\",\n },\n ],\n });\n\n console.log(messageThread);\n}\n\nmain();"
response: "{\n id: 'thread_abc123',\n object: 'thread',\n created_at: 1699014083,\n metadata: {}\n}\n"
/threads/{thread_id}:
get:
operationId: getThread
tags:
- Threads
summary: OpenAI Retrieves a thread.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ThreadObject'
x-oaiMeta:
name: Retrieve thread
group: threads
beta: true
returns: The [thread](/docs/api-reference/threads/object) object matching the specified ID.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: 'from openai import OpenAI
client = OpenAI()
my_thread = client.beta.threads.retrieve("thread_abc123")
print(my_thread)
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const myThread = await openai.beta.threads.retrieve(\n \"thread_abc123\"\n );\n\n console.log(myThread);\n}\n\nmain();"
response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1699014083,\n \"metadata\": {}\n}\n"
post:
operationId: modifyThread
tags:
- Threads
summary: OpenAI Modifies a thread.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to modify. Only the `metadata` can be modified.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyThreadRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ThreadObject'
x-oaiMeta:
name: Modify thread
group: threads
beta: true
returns: The modified [thread](/docs/api-reference/threads/object) object matching the specified ID.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"metadata\": {\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmy_updated_thread = client.beta.threads.update(\n \"thread_abc123\",\n metadata={\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n)\nprint(my_updated_thread)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const updatedThread = await openai.beta.threads.update(\n \"thread_abc123\",\n {\n metadata: { modified: \"true\", user: \"abc123\" },\n }\n );\n\n console.log(updatedThread);\n}\n\nmain();"
response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread\",\n \"created_at\": 1699014083,\n \"metadata\": {\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n}\n"
delete:
operationId: deleteThread
tags:
- Threads
summary: OpenAI Delete a thread.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to delete.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteThreadResponse'
x-oaiMeta:
name: Delete thread
group: threads
beta: true
returns: Deletion status
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -X DELETE\n"
python: 'from openai import OpenAI
client = OpenAI()
response = client.beta.threads.delete("thread_abc123")
print(response)
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.beta.threads.del(\"thread_abc123\");\n\n console.log(response);\n}\nmain();"
response: "{\n \"id\": \"thread_abc123\",\n \"object\": \"thread.deleted\",\n \"deleted\": true\n}\n"
/threads/{thread_id}/messages:
get:
operationId: listMessages
tags:
- Threads
summary: OpenAI Returns a list of messages for a given thread.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the [thread](/docs/api-reference/threads) the messages belong to.
- name: limit
in: query
description: 'A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
'
required: false
schema:
type: integer
default: 20
- name: order
in: query
description: 'Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
'
schema:
type: string
default: desc
enum:
- asc
- desc
- name: after
in: query
description: 'A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
'
schema:
type: string
- name: before
in: query
description: 'A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessagesResponse'
x-oaiMeta:
name: List messages
group: threads
beta: true
returns: A list of [message](/docs/api-reference/messages) objects.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123/messages \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: 'from openai import OpenAI
client = OpenAI()
thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)
'
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const threadMessages = await openai.beta.threads.messages.list(\n \"thread_abc123\"\n );\n\n console.log(threadMessages.data);\n}\n\nmain();"
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1699016383,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"How does AI work? Explain it in simple terms.\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {}\n },\n {\n \"id\": \"msg_abc456\",\n \"object\": \"thread.message\",\n \"created_at\": 1699016383,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"Hello, what is AI?\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [\n \"file-abc123\"\n ],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {}\n }\n ],\n \"first_id\": \"msg_abc123\",\n \"last_id\": \"msg_abc456\",\n \"has_more\": false\n}\n"
post:
operationId: createMessage
tags:
- Threads
summary: OpenAI Create a message.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the [thread](/docs/api-reference/threads) to create a message for.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMessageRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessageObject'
x-oaiMeta:
name: Create message
group: threads
beta: true
returns: A [message](/docs/api-reference/messages/object) object.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123/messages \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"role\": \"user\",\n \"content\": \"How does AI work? Explain it in simple terms.\"\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nthread_message = client.beta.threads.messages.create(\n \"thread_abc123\",\n role=\"user\",\n content=\"How does AI work? Explain it in simple terms.\",\n)\nprint(thread_message)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const threadMessages = await openai.beta.threads.messages.create(\n \"thread_abc123\",\n { role: \"user\", content: \"How does AI work? Explain it in simple terms.\" }\n );\n\n console.log(threadMessages);\n}\n\nmain();"
response: "{\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1699017614,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"How does AI work? Explain it in simple terms.\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {}\n}\n"
/threads/{thread_id}/messages/{message_id}:
get:
operationId: getMessage
tags:
- Threads
summary: OpenAI Retrieve a message.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the [thread](/docs/api-reference/threads) to which this message belongs.
- in: path
name: message_id
required: true
schema:
type: string
description: The ID of the message to retrieve.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessageObject'
x-oaiMeta:
name: Retrieve message
group: threads
beta: true
returns: The [message](/docs/api-reference/threads/messages/object) object matching the specified ID.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmessage = client.beta.threads.messages.retrieve(\n message_id=\"msg_abc123\",\n thread_id=\"thread_abc123\",\n)\nprint(message)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const message = await openai.beta.threads.messages.retrieve(\n \"thread_abc123\",\n \"msg_abc123\"\n );\n\n console.log(message);\n}\n\nmain();"
response: "{\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1699017614,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"How does AI work? Explain it in simple terms.\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {}\n}\n"
post:
operationId: modifyMessage
tags:
- Threads
summary: OpenAI Modifies a message.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to which this message belongs.
- in: path
name: message_id
required: true
schema:
type: string
description: The ID of the message to modify.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModifyMessageRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MessageObject'
x-oaiMeta:
name: Modify message
group: threads
beta: true
returns: The modified [message](/docs/api-reference/threads/messages/object) object.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"metadata\": {\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nmessage = client.beta.threads.messages.update(\n message_id=\"msg_abc12\",\n thread_id=\"thread_abc123\",\n metadata={\n \"modified\": \"true\",\n \"user\": \"abc123\",\n },\n)\nprint(message)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const message = await openai.beta.threads.messages.update(\n \"thread_abc123\",\n \"msg_abc123\",\n {\n metadata: {\n modified: \"true\",\n user: \"abc123\",\n },\n }\n }'"
response: "{\n \"id\": \"msg_abc123\",\n \"object\": \"thread.message\",\n \"created_at\": 1699017614,\n \"thread_id\": \"thread_abc123\",\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": {\n \"value\": \"How does AI work? Explain it in simple terms.\",\n \"annotations\": []\n }\n }\n ],\n \"file_ids\": [],\n \"assistant_id\": null,\n \"run_id\": null,\n \"metadata\": {\n \"modified\": \"true\",\n \"user\": \"abc123\"\n }\n}\n"
/threads/runs:
post:
operationId: createThreadAndRun
tags:
- Threads
summary: OpenAI Create a thread and run it in one request.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateThreadAndRunRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RunObject'
x-oaiMeta:
name: Create thread and run
group: threads
beta: true
returns: A [run](/docs/api-reference/runs/object) object.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/runs \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\" \\\n -d '{\n \"assistant_id\": \"asst_abc123\",\n \"thread\": {\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Explain deep learning to a 5 year old.\"}\n ]\n }\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nrun = client.beta.threads.create_and_run(\n assistant_id=\"asst_abc123\",\n thread={\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Explain deep learning to a 5 year old.\"}\n ]\n }\n)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const run = await openai.beta.threads.createAndRun({\n assistant_id: \"asst_abc123\",\n thread: {\n messages: [\n { role: \"user\", content: \"Explain deep learning to a 5 year old.\" },\n ],\n },\n });\n\n console.log(run);\n}\n\nmain();\n"
response: "{\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699076792,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"queued\",\n \"started_at\": null,\n \"expires_at\": 1699077392,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": null,\n \"last_error\": null,\n \"model\": \"gpt-4\",\n \"instructions\": \"You are a helpful assistant.\",\n \"tools\": [],\n \"file_ids\": [],\n \"metadata\": {},\n \"usage\": null\n}\n"
/threads/{thread_id}/runs:
get:
operationId: listRuns
tags:
- Threads
summary: OpenAI Returns a list of runs belonging to a thread.
parameters:
- name: thread_id
in: path
required: true
schema:
type: string
description: The ID of the thread the run belongs to.
- name: limit
in: query
description: 'A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
'
required: false
schema:
type: integer
default: 20
- name: order
in: query
description: 'Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
'
schema:
type: string
default: desc
enum:
- asc
- desc
- name: after
in: query
description: 'A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
'
schema:
type: string
- name: before
in: query
description: 'A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ListRunsResponse'
x-oaiMeta:
name: List runs
group: threads
beta: true
returns: A list of [run](/docs/api-reference/runs/object) objects.
examples:
request:
curl: "curl https://api.openai.com/v1/threads/thread_abc123/runs \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"OpenAI-Beta: assistants=v1\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nruns = client.beta.threads.runs.list(\n \"thread_abc123\"\n)\nprint(runs)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const runs = await openai.beta.threads.runs.list(\n \"thread_abc123\"\n );\n\n console.log(runs);\n}\n\nmain();\n"
response: "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"run_abc123\",\n \"object\": \"thread.run\",\n \"created_at\": 1699075072,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"completed\",\n \"started_at\": 1699075072,\n \"expires_at\": null,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": 1699075073,\n \"last_error\": null,\n \"model\": \"gpt-3.5-turbo\",\n \"instructions\": null,\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\",\n \"file-abc456\"\n ],\n \"metadata\": {},\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n },\n {\n \"id\": \"run_abc456\",\n \"object\": \"thread.run\",\n \"created_at\": 1699063290,\n \"assistant_id\": \"asst_abc123\",\n \"thread_id\": \"thread_abc123\",\n \"status\": \"completed\",\n \"started_at\": 1699063290,\n \"expires_at\": null,\n \"cancelled_at\": null,\n \"failed_at\": null,\n \"completed_at\": 1699063291,\n \"last_error\": null,\n \"model\": \"gpt-3.5-turbo\",\n \"instructions\": null,\n \"tools\": [\n {\n \"type\": \"code_interpreter\"\n }\n ],\n \"file_ids\": [\n \"file-abc123\",\n \"file-abc456\"\n ],\n \"metadata\": {},\n \"usage\": {\n \"prompt_tokens\": 123,\n \"completion_tokens\": 456,\n \"total_tokens\": 579\n }\n }\n ],\n \"first_id\": \"run_abc123\",\n \"last_id\": \"run_abc456\",\n \"has_more\": false\n}\n"
post:
operationId: createRun
tags:
- Threads
summary: OpenAI Create a run.
parameters:
- in: path
name: thread_id
required: true
schema:
type: string
description: The ID of the thread to run.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRunRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/compon
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-threads-api-openapi.yml