Skip to main content
In this guide, we will show how to create, view, and inspect threads.

​
Create a thread

To run your graph and the state persisted, you must first create a thread.

​
Empty thread

To create a new thread, use the LangGraph SDK create method. See the Python and JS SDK reference docs for more information.
  • Python
  • Javascript
  • CURL
from langgraph_sdk import get_client

client = get_client(url=<DEPLOYMENT_URL>)
thread = await client.threads.create()

print(thread)
Output: 
{
"thread_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2025-05-12T14:04:08.268Z",
"updated_at": "2025-05-12T14:04:08.268Z",
"metadata": {},
"status": "idle",
"values": {}
}

​
Copy thread

Alternatively, if you already have a thread in your application whose state you wish to copy, you can use the copy method. This will create an independent thread whose history is identical to the original thread at the time of the operation. See the Python and JS SDK reference docs for more information.
  • Python
  • Javascript
  • CURL
copied_thread = await client.threads.copy(<THREAD_ID>)

​
Prepopulated State

Finally, you can create a thread with an arbitrary pre-defined state by providing a list of supersteps into the create method. The supersteps describe a list of a sequence of state updates. For example:
  • Python
  • Javascript
  • CURL
from langgraph_sdk import get_client

client = get_client(url=<DEPLOYMENT_URL>)
thread = await client.threads.create(
  graph_id="agent",
  supersteps=[
    {
      updates: [
        {
          values: {},
          as_node: '__input__',
        },
      ],
    },
    {
      updates: [
        {
          values: {
            messages: [
              {
                type: 'human',
                content: 'hello',
              },
            ],
          },
          as_node: '__start__',
        },
      ],
    },
    {
      updates: [
        {
          values: {
            messages: [
              {
                content: 'Hello! How can I assist you today?',
                type: 'ai',
              },
            ],
          },
          as_node: 'call_model',
        },
      ],
    },
  ])

print(thread)
Output: 
{
"thread_id": "f15d70a1-27d4-4793-a897-de5609920b7d",
"created_at": "2025-05-12T15:37:08.935038+00:00",
"updated_at": "2025-05-12T15:37:08.935046+00:00",
"metadata": {"graph_id": "agent"},
"status": "idle",
"config": {},
"values": {
"messages": [
{
"content": "hello",
"additional_kwargs": {},
"response_metadata": {},
"type": "human",
"name": null,
"id": "8701f3be-959c-4b7c-852f-c2160699b4ab",
"example": false
},
{
"content": "Hello! How can I assist you today?",
"additional_kwargs": {},
"response_metadata": {},
"type": "ai",
"name": null,
"id": "4d8ea561-7ca1-409a-99f7-6b67af3e1aa3",
"example": false,
"tool_calls": [],
"invalid_tool_calls": [],
"usage_metadata": null
}
]
}
}

​
List threads

​
LangGraph SDK

To list threads, use the LangGraph SDK search method. This will list the threads in the application that match the provided filters. See the Python and JS SDK reference docs for more information.

​
Filter by thread status

Use the status field to filter threads based on their status. Supported values are idle, busy, interrupted, and error. See here for information on each status. For example, to view idle threads:
  • Python
  • Javascript
  • CURL
print(await client.threads.search(status="idle",limit=1))
Output: 
[
{
'thread_id': 'cacf79bb-4248-4d01-aabc-938dbd60ed2c',
'created_at': '2024-08-14T17:36:38.921660+00:00',
'updated_at': '2024-08-14T17:36:38.921660+00:00',
'metadata': {'graph_id': 'agent'},
'status': 'idle',
'config': {'configurable': {}}
}
]

​
Filter by metadata

The search method allows you to filter on metadata:
  • Python
  • Javascript
  • CURL
print((await client.threads.search(metadata={"graph_id":"agent"},limit=1)))
Output: 
[
{
'thread_id': 'cacf79bb-4248-4d01-aabc-938dbd60ed2c',
'created_at': '2024-08-14T17:36:38.921660+00:00',
'updated_at': '2024-08-14T17:36:38.921660+00:00',
'metadata': {'graph_id': 'agent'},
'status': 'idle',
'config': {'configurable': {}}
}
]

​
Sorting

The SDK also supports sorting threads by thread_id, status, created_at, and updated_at using the sort_by and sort_order params.

​
LangSmith UI

You can also view threads in a deployment via the LangSmith UI. Inside your deployment, select the “Threads” tab. This will load a table of all of the threads in your deployment. To filter by thread status, select a status in the top bar. To sort by a supported property, click on the arrow icon for the desired column.

​
Inspect threads

​
LangGraph SDK

​
Get Thread

To view a specific thread given its thread_id, use the get method:
  • Python
  • Javascript
  • CURL
print((await client.threads.get(<THREAD_ID>)))
Output: 
{
'thread_id': 'cacf79bb-4248-4d01-aabc-938dbd60ed2c',
'created_at': '2024-08-14T17:36:38.921660+00:00',
'updated_at': '2024-08-14T17:36:38.921660+00:00',
'metadata': {'graph_id': 'agent'},
'status': 'idle',
'config': {'configurable': {}}
}

​
Inspect Thread State

To view the current state of a given thread, use the get_state method:
  • Python
  • Javascript
  • CURL
print((await client.threads.get_state(<THREAD_ID>)))
Output: 
{
"values": {
"messages": [
{
"content": "hello",
"additional_kwargs": {},
"response_metadata": {},
"type": "human",
"name": null,
"id": "8701f3be-959c-4b7c-852f-c2160699b4ab",
"example": false
},
{
"content": "Hello! How can I assist you today?",
"additional_kwargs": {},
"response_metadata": {},
"type": "ai",
"name": null,
"id": "4d8ea561-7ca1-409a-99f7-6b67af3e1aa3",
"example": false,
"tool_calls": [],
"invalid_tool_calls": [],
"usage_metadata": null
}
]
},
"next": [],
"tasks": [],
"metadata": {
"thread_id": "f15d70a1-27d4-4793-a897-de5609920b7d",
"checkpoint_id": "1f02f46f-7308-616c-8000-1b158a9a6955",
"graph_id": "agent_with_quite_a_long_name",
"source": "update",
"step": 1,
"writes": {
"call_model": {
"messages": [
{
"content": "Hello! How can I assist you today?",
"type": "ai"
}
]
}
},
"parents": {}
},
"created_at": "2025-05-12T15:37:09.008055+00:00",
"checkpoint": {
"checkpoint_id": "1f02f46f-733f-6b58-8001-ea90dcabb1bd",
"thread_id": "f15d70a1-27d4-4793-a897-de5609920b7d",
"checkpoint_ns": ""
},
"parent_checkpoint": {
"checkpoint_id": "1f02f46f-7308-616c-8000-1b158a9a6955",
"thread_id": "f15d70a1-27d4-4793-a897-de5609920b7d",
"checkpoint_ns": ""
},
"checkpoint_id": "1f02f46f-733f-6b58-8001-ea90dcabb1bd",
"parent_checkpoint_id": "1f02f46f-7308-616c-8000-1b158a9a6955"
}
Optionally, to view the state of a thread at a given checkpoint, simply pass in the checkpoint id (or the entire checkpoint object):
  • Python
  • Javascript
  • CURL
thread_state = await client.threads.get_state(
  thread_id=<THREAD_ID>
  checkpoint_id=<CHECKPOINT_ID>
)

​
Inspect Full Thread History

To view a thread’s history, use the get_history method. This returns a list of every state the thread experienced. For more information see the Python and JS reference docs.

​
LangSmith UI

You can also view threads in a deployment via the LangSmith UI. Inside your deployment, select the “Threads” tab. This will load a table of all of the threads in your deployment. Select a thread to inspect its current state. To view its full history and for further debugging, open the thread in Studio.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I