Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Openai Threads API
version: 2.0.0
contact:
name: OpenAI Support
url: https://help.openai.com/
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
termsOfService: https://openai.com/policies/terms-of-use
description: 'Operations tagged Threads across 2 of this provider''s published API definitions: files-openapi-original.yml, threads-openapi-original.yml. Each path carries the servers of the definition it was published in.'
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"
servers:
- url: https://api.openai.com/v1
/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"
servers:
- url: https://api.openai.com/v1
/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"
servers:
- url: https://api.openai.com/v1
/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"
servers:
- url: https://api.openai.com/v1
/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"
servers:
- url: https://api.openai.com/v1
/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"
servers:
- url: https://api.openai.com/v1
/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"
servers:
- url: https://api.openai.com/v1
/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:
# --- 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