Use threads

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

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

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

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

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

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.

LangGraph Platform UI

You can also view threads in a deployment via the LangGraph Platform 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

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

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

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.

LangGraph Platform UI

You can also view threads in a deployment via the LangGraph Platform 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 LangGraph Studio.