v1
latestOpenAPI 3.0.02026-08-04891301.4 MBList threads for a user
Returns all threads visible to the specified user. The authenticated caller must have access to the target user's account; a 403 is returned otherwise.
Pass one or more agent IDs to narrow results to threads where at least one of the listed agents is also a member — useful for displaying every thread a user shares with a particular agent. Pass one or more filter objects to narrow results by thread metadata key/value pairs. Both narrowings may be combined in a single request.
Results are returned as a flat array; no cursor-based pagination is applied.
get/api/v1/users/{user}/threads
Path parameters
userstring required
User ID (usr_...) whose threads should be listed.
Query parameters
agentstring[]
Array of agent user IDs (usr_...). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership.
Array of metadata filter objects. Each filter matches threads whose metadata map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata.
[
{
"key": "string",
"type": "metadata",
"value": "string"
}
]Response
Successful response
Example response
{
"data": [
{
"agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
"created_at": "2024-01-01T00:00:00Z",
"creator": {
"alias": "jdoe",
"app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
"app_name": "Example Name",
"email": "user@example.com",
"id": "usr_0aBcDeFgHiJkLmNoPqRsTu",
"is_system_user": true,
"metadata": {
"key": "value"
},
"name": "Example Name",
"org": "org_0aBcDeFgHiJkLmNoPqRsTu",
"org_name": "Example Name",
"org_role": "member",
"sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
"sandbox_name": "Example Name"
},
"description": "An example description.",
"id": "string",
"is_channel": true,
"is_default": true,
"is_transient": true,
"is_unlisted": true,
"key": "string",
"last_activity": "2024-01-01T00:00:00Z",
"metadata": {
"key": "value"
},
"muted": true,
"org": "org_0aBcDeFgHiJkLmNoPqRsTu",
"parent_message": {
"actors": [
{
"alias": "alice",
"id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
"name": "Example Name",
"profile_picture": {
"file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
"height": 600,
"media": "med_0aBcDeFgHiJkLmNoPqRsTu",
"mime_type": "application/json",
"refresh_url": "https://example.com",
"url": "https://example.com",
"width": 800
}
}
],
"agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
"attachments": [
{
"content_type": "application/json",
"description": "An example description.",
"filename": "string",
"height": 1,
"id": "string",
"image_height": 1,
"image_source": {
"file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
"height": 600,
"media": "med_0aBcDeFgHiJkLmNoPqRsTu",
"mime_type": "application/json",
"refresh_url": "https://example.com",
"url": "https://example.com",
"width": 800
},
"image_url": "https://example.com",
"image_width": 1,
"media_type": "application/json",
"name": "Example Name",
"object": {},
"title": "Example Title",
"type": "file",
"url": "https://example.com",
"variants": [
{
"content_type": "application/json",
"created_at": "2024-01-01T00:00:00Z",
"file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
"filename": "string",
"height": 600,
"id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
"image_source": {
"file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
"height": 600,
"media": "med_0aBcDeFgHiJkLmNoPqRsTu",
"mime_type": "application/json",
"refresh_url": "https://example.com",
"url": "https://example.com",
"width": 800
},
"updated_at": "2024-01-01T00:00:00Z",
"url": "https://example.com",
"variant_key": "original",
"width": 800
}
],
"version": 1,
"width": 1
}
],
"branched_thread": "string",
"content": "Hello, how can I help you today?",
"created_at": "2024-01-01T00:00:00Z",
"has_replies": true,
"id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
"idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
"legacy_agent": "string",
"metadata": {
"key": "value"
},
"org": "org_0aBcDeFgHiJkLmNoPqRsTu",
"reactions": [
{
"payload": {
"key": "value"
},
"type": "emoji_reaction",
"user": "string"
}
],
"rendering_mode": "reply",
"replies": [
{}
],
"replies_after_cursor": "string",
"replies_before_cursor": "string",
"reply_count": 1,
"reply_to": {},
"sandbox": "string",
"team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
"thread": "string",
"user": "string"
},
"participant": [
"string"
],
"participants": [
{
"alias": "jdoe",
"app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
"app_name": "Example Name",
"email": "user@example.com",
"id": "usr_0aBcDeFgHiJkLmNoPqRsTu",
"is_system_user": true,
"metadata": {
"key": "value"
},
"name": "Example Name",
"org": "org_0aBcDeFgHiJkLmNoPqRsTu",
"org_name": "Example Name",
"org_role": "member",
"sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
"sandbox_name": "Example Name"
}
],
"participating_actor": [
"string"
],
"participating_agents": [
{
"acl": {
"add": [
{
"actions": [
"read",
"write"
],
"principal": "string",
"principal_type": "user"
}
],
"grants": [
{
"actions": [
"read",
"write"
],
"principal": "string",
"principal_type": "user"
}
],
"remove": [
{
"principal": "string",
"principal_type": "user"
}
]
},
"app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
"created_at": "2024-01-01T00:00:00Z",
"default_model": "claude-3-7-sonnet-latest",
"email": "user@example.com",
"id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
"identity": "You are a helpful assistant that answers questions about ArchAstro products.",
"last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
"lookup_key": "string",
"metadata": {
"key": "value"
},
"name": "Example Name",
"org": "org_0aBcDeFgHiJkLmNoPqRsTu",
"org_name": "Example Name",
"originator": "deploy-pipeline",
"phone_number": "+15555550123",
"sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
"source_solution": {
"solution": {
"category_keys": [
"string"
],
"created_at": "2024-01-01T00:00:00Z",
"description": "An example description.",
"id": "id_0aBcDeFgHiJkLmNoPqRsTu",
"kind": "Solution",
"latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu",
"latest_version": "1.0.0",
"lookup_key": "string",
"metadata": {
"key": "value"
},
"name": "Example Name",
"org": "org_0aBcDeFgHiJkLmNoPqRsTu",
"org_logo": {
"file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
"height": 600,
"media": "med_0aBcDeFgHiJkLmNoPqRsTu",
"mime_type": "application/json",
"refresh_url": "https://example.com",
"url": "https://example.com",
"width": 800
},
"org_name": "Example Name",
"org_slug": "example-slug",
"owners": [
"string"
],
"readme_url": "https://example.com",
"solution_id": "01234567-89ab-cdef-0123-456789abcdef",
"solution_version": "1.2.0",
"tag_keys": [
"string"
],
"template_kind": "AgentTemplate",
"templates": [
{
"description": "An example description.",
"display_name": "Example Name",
"id": "id_0aBcDeFgHiJkLmNoPqRsTu",
"kind": "AgentTemplate",
"lookup_key": "string",
"name": "Example Name",
"readme_url": "https://example.com",
"virtual_path": "string"
}
],
"updated_at": "2024-01-01T00:00:00Z",
"upgrade_available": true,
"virtual_path": "string"
},
"template": {
"created_at": "2024-01-01T00:00:00Z",
"description": "An example description.",
"display_name": "Example Name",
"id": "id_0aBcDeFgHiJkLmNoPqRsTu",
"kind": "agent_tool_template",
"lookup_key": "string",
"name": "Example Name",
"updated_at": "2024-01-01T00:00:00Z",
"virtual_path": "string"
}
},
"team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
"updated_at": "2024-01-01T00:00:00Z",
"user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}
],
"role": "member",
"sandbox": "string",
"settings": {
"agent_enabled": true
},
"slug": "example-slug",
"sub_threads": [
{}
],
"team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
"title": "Example Title",
"ttl": 3600,
"unread_count": 5,
"updated_at": "2024-01-01T00:00:00Z",
"user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}
]
}