# List threads

div
strong
🔨 In Development
 — This section is still being developed and may change.


Retrieve a paginated list of threads with filtering options for assistant, organization, and visibility.

Retrieve a paginated list of threads with filtering options for assistant, organization, and visibility. Uses cursor-based pagination for efficient navigation through large result sets.

#### Query Parameters

**`limit`** integer optional · Defaults to `20`

Number of threads to return. Must be between 1 and 100.

**`order`** string optional · Defaults to `desc`

Sort order for threads. Available values: `asc` (oldest first), `desc` (newest first).

**`after`** string optional

Cursor for pagination. Returns threads created after the specified thread ID.

**`before`** string optional

Cursor for pagination. Returns threads created before the specified thread ID.

**`assistantId`** string optional

Filter threads by assistant ID. Only returns threads bound to the specified assistant.

**`visibleInUi`** boolean optional

Filter threads by UI visibility. `true` returns only visible threads, `false` returns only hidden threads.

Basic

```bash
curl "https://api.freddy.aitronos.com/v1/threads?limit=20" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests

response = requests.get(
    "https://api.freddy.aitronos.com/v1/threads",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"limit": 20}
)

threads = response.json()
print(f"Found {len(threads['data'])} threads")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/threads?limit=20', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

const threads = await response.json();
console.log(`Found ${threads.data.length} threads`);
```

With Filters

```bash
curl "https://api.freddy.aitronos.com/v1/threads?assistantId=asst_support_agent&visibleInUi=true&limit=10" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests

response = requests.get(
    "https://api.freddy.aitronos.com/v1/threads",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "assistantId": "asst_support_agent",
        "visibleInUi": True,
        "limit": 10
    }
)

threads = response.json()
print(f"Found {len(threads['data'])} support threads")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/threads?assistantId=asst_support_agent&visibleInUi=true&limit=10', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

const threads = await response.json();
console.log(`Found ${threads.data.length} support threads`);
```

Pagination

```bash
# First page
curl "https://api.freddy.aitronos.com/v1/threads?limit=5" \
  -H "Authorization: Bearer $FREDDY_API_KEY"

# Next page (using last_id from previous response)
curl "https://api.freddy.aitronos.com/v1/threads?limit=5&after=thread_abc123" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests

def get_threads_page(limit=5, after=None):
    params = {"limit": limit}
    if after:
        params["after"] = after
    
    response = requests.get(
        "https://api.freddy.aitronos.com/v1/threads",
        headers={"Authorization": f"Bearer {api_key}"},
        params=params
    )
    return response.json()

# Get first page
first_page = get_threads_page(5)
print(f"First page: {len(first_page['data'])} threads")

# Get next page
if first_page['has_more']:
    next_page = get_threads_page(5, first_page['last_id'])
    print(f"Next page: {len(next_page['data'])} threads")
```


```javascript
async function getThreadsPage(limit = 5, after = null) {
  const params = new URLSearchParams({ limit: limit.toString() });
  if (after) params.append('after', after);
  
  const response = await fetch(`https://api.freddy.aitronos.com/v1/threads?${params}`, {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  });
  
  return await response.json();
}

// Get first page
const firstPage = await getThreadsPage(5);
console.log(`First page: ${firstPage.data.length} threads`);

// Get next page
if (firstPage.has_more) {
  const nextPage = await getThreadsPage(5, firstPage.last_id);
  console.log(`Next page: ${nextPage.data.length} threads`);
}
```

## Response

200 OK

```json
{
  "object": "list",
  "data": [
    {
      "id": "thread_abc123",
      "object": "thread",
      "createdAt": 1741476542,
      "updatedAt": 1741476600,
      "metadata": {
        "category": "support",
        "priority": "high"
      },
      "assistantId": "asst_support_agent",
      "organizationId": "ORG_123",
      "userId": "uid_user123",
      "title": "Customer Support Query",
      "visibleInUi": true,
      "messageCount": 5,
      "status": "streaming"
    },
    {
      "id": "thread_xyz789",
      "object": "thread",
      "createdAt": 1741476000,
      "updatedAt": 1741476100,
      "metadata": {},
      "assistantId": null,
      "organizationId": "ORG_123",
      "userId": "uid_user123",
      "title": "General Question",
      "visibleInUi": true,
      "messageCount": 2,
      "status": "inactive"
    }
  ],
  "firstId": "thread_abc123",
  "lastId": "thread_xyz789",
  "hasMore": true
}
```

Errors

```json 400 Bad Request
{
  "error": {
    "message": "Invalid limit parameter",
    "type": "invalid_request_error",
    "code": "invalid_limit",
    "param": "limit"
  }
}
```


```json 401 Unauthorized
{
  "error": {
    "message": "Authentication required",
    "type": "authentication_error",
    "code": "missing_authentication"
  }
}
```


```json 403 Forbidden
{
  "error": {
    "message": "Access denied to organization threads",
    "type": "permission_error",
    "code": "insufficient_permissions"
  }
}
```

## Related Resources

- [Threads Overview](/docs/documentation/core-concepts/threads-overview)
- [Create Thread](/docs/api-reference/threads/create)
- [Retrieve Thread](/docs/api-reference/threads/retrieve)
- [Thread Context Modes](/docs/documentation/core-concepts/thread-context-modes)