# List assistants

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


Get all assistants the user has access to across organizations with pagination, search, and filtering capabilities.

#### Query Parameters

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

Maximum number of assistants to return (1-100).

**`offset`** integer optional · Defaults to `0`

Number of assistants to skip for pagination.

**`page`** integer optional · Defaults to `1`

Page number for pagination (≥1).

**`page_size`** integer optional · Defaults to `100`

Number of assistants per page (1-1000).

**`search`** string optional

Search assistants by name or description.

**`access_mode`** string optional

Filter by access mode. One of `private`, `restricted`, `department`, `organization`, `global`, `public`.

**`include_inactive`** boolean optional · Defaults to `false`

Whether to include inactive assistants in results.

**`sort_by`** string optional · Defaults to `name`

Sort order. One of `name`, `created_at`, `updated_at`.

**`sort_order`** string optional · Defaults to `asc`

Sort direction. One of `asc`, `desc`.

**`fields`** string optional · Defaults to `summary`

Control the amount of data returned per assistant. Values:

- `summary` - UI list view essentials (id, name, description, created_at, updated_at, access_mode, api_enabled, is_active, temperature)
- `standard` - Summary + model configuration (default_model_key, allowed_model_providers, data_analysis_enabled, context_strategy)
- `full` - Complete [Assistant object](/docs/api-reference/objects/assistant-object) with all fields including detailed tool configurations, permissions, and metadata


Use `summary` for list views to minimize payload size. Use `full` only when displaying individual assistant details.

## Returns

**`assistants`** array

Array of [Assistant objects](/docs/api-reference/objects/assistant-object). The fields included depend on the `fields` query parameter.

**`total`** integer

Total number of assistants matching the query across all pages.

**`organization_id`** string or null

The organization ID for the current context. Can be `null` for cross-organization queries.

**`pagination`** object

Pagination information for navigating through results.

- `total` - Total number of items matching the query
- `limit` - Maximum number of items returned
- `offset` - Number of items skipped
- `has_more` - Whether more results exist


**`filters_applied`** object

Summary of filters applied to the query.

- `search` - Search term used (if any)
- `access_mode` - Access mode filter (if any)
- `include_inactive` - Whether inactive assistants are included
- `sort_by` - Field used for sorting
- `sort_order` - Sort direction (`asc` or `desc`)


**`user_context`** object

Information about the current user's context.

- `user_id` - Current user's ID
- `organization_count` - Number of organizations the user has access to


Basic List

```bash
curl "https://api.freddy.aitronos.com/v1/assistants" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests

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

assistants = response.json()
print(f"Found {assistants['total_count']} assistants")
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/assistants', {
  headers: {
    'Authorization': `Bearer ${api_key}`
  }
});

const assistants = await response.json();
console.log(`Found ${assistants.total_count} assistants`);
```

Summary (Minimal)

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


```python
import requests

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

assistants = response.json()
# Returns only: id, name, description, is_active, access_mode, created_at, updated_at
# Perfect for list views - ~70% smaller payload
```


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

const assistants = await response.json();
// Returns only: id, name, description, is_active, access_mode, created_at, updated_at
// Perfect for list views - ~70% smaller payload
```

With Filters

```bash
curl "https://api.freddy.aitronos.com/v1/assistants?search=chat&access_mode=public&fields=standard&limit=10" \
  -H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests

response = requests.get(
    "https://api.freddy.aitronos.com/v1/assistants",
    headers={"Authorization": f"Bearer {api_key}"},
    params={
        "search": "chat",
        "access_mode": "public",
        "fields": "standard",
        "limit": 10
    }
)

assistants = response.json()
```


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/assistants?search=chat&access_mode=public&fields=standard&limit=10', {
  headers: {
    'Authorization': `Bearer ${api_key}`
  }
});

const assistants = await response.json();
```

## Response

Summary (Default)
Minimal payload with only UI-essential fields. Optimized for list views.


```json
{
  "assistants": [
    {
      "id": "ass_0c23daea5e34",
      "name": "Customer Support Bot",
      "description": "AI assistant for customer support",
      "created_at": "2025-01-20T10:30:00Z",
      "updated_at": "2025-01-20T14:45:00Z",
      "access_mode": "organization",
      "api_enabled": true,
      "is_active": true,
      "temperature": 0.7,
      "max_tokens": 4000
    },
    {
      "id": "ass_5f89bcd2a1e7",
      "name": "Sales Assistant",
      "description": "AI assistant for sales inquiries",
      "created_at": "2025-01-18T14:22:00Z",
      "updated_at": "2025-01-19T09:15:00Z",
      "access_mode": "department",
      "api_enabled": false,
      "is_active": true,
      "temperature": 0.8,
      "max_tokens": 2000
    }
  ],
  "total": 42,
  "organization_id": "ORG_797C4DDB256A300C",
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "user_context": {
    "user_id": "uid_82f788837a21",
    "organization_count": 3
  },
  "filters_applied": {
    "search": null,
    "access_mode": null,
    "include_inactive": false,
    "sort_by": "name",
    "sort_order": "asc"
  }
}
```

Standard
Summary fields plus model and basic configuration. Good balance between size and information.


```json
{
  "assistants": [
    {
      "id": "ass_0c23daea5e34",
      "name": "Customer Support Bot",
      "description": "AI assistant for customer support",
      "created_at": "2025-01-20T10:30:00Z",
      "updated_at": "2025-01-20T14:45:00Z",
      "access_mode": "organization",
      "api_enabled": true,
      "is_active": true,
      "temperature": 0.7,
      "default_model_key": "gpt-4o",
      "allowed_model_providers": ["openai", "anthropic"],
      "context_strategy": "auto"
    }
  ],
  "total": 1,
  "organization_id": "ORG_797C4DDB256A300C",
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  },
  "user_context": {
    "user_id": "uid_82f788837a21",
    "organization_count": 3
  },
  "filters_applied": {
    "search": null,
    "access_mode": null,
    "include_inactive": false,
    "sort_by": "name",
    "sort_order": "asc"
  }
}
```

Full
Complete [Assistant objects](/docs/api-reference/objects/assistant-object) with all fields and detailed configurations. See the Assistant object documentation for field descriptions.


```json
{
  "assistants": [
    {
      "id": "ass_0c23daea5e34",
      "organization_id": "ORG_797C4DDB256A300C",
      "created_by": "uid_82f788837a21",
      "created_at": "2025-01-20T10:30:00Z",
      "updated_at": "2025-01-20T14:45:00Z",
      "deleted_at": null,
      "name": "Customer Support Bot",
      "avatar_id": "avt_support_green",
      "default_model_key": "gpt-4o",
      "allowed_model_providers": ["openai", "anthropic"],
      "instructions": "You are a helpful customer support assistant...",
      "tool_configurations": {
        "system_tools": {
          "web_search": {
            "mode": "auto",
            "sources": true
          },
          "file_search": {
            "mode": "on",
            "results": true
          },
          "code_interpreter": {
            "mode": "off"
          }
        },
      "mcp_tools": [],
      "streamline_tools": []
    },
    "system_message": null,
    "context_strategy": "auto",
    "max_output_synapses": 4096,
      "max_tool_calls": 10,
      "parallel_tool_calls": false,
      "reasoning": null,
      "service_tier": "default",
      "store": true,
      "temperature": 0.7,
      "text_configuration": {},
      "top_logprobs": 0,
      "top_p": 1.0,
      "truncation": "disabled",
  "access_mode": "organization",
  "access_departments": [],
  "access_users": [],
  "editable_by_users": [],
  "visible_in_chat_to_users": [],
  "editable_by_roles": ["admin", "manager"],
  "visible_to_roles": ["member", "admin"],
  "vector_store_ids": ["vs_abc123"],
      "api_enabled": true,
      "is_active": true,
      "metadata": {
        "department": "customer_success"
      },
      "rules_attached": []
    }
  ],
  "total": 1,
  "organization_id": "ORG_797C4DDB256A300C",
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  },
  "user_context": {
    "user_id": "uid_82f788837a21",
    "organization_count": 3
  },
  "filters_applied": {
    "search": null,
    "access_mode": null,
    "include_inactive": false,
    "sort_by": "name",
    "sort_order": "asc"
  }
}
```

Errors
**400 Bad Request**


```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid access mode. Must be one of: public, private, organization",
    "trace_id": "trace_abc123"
  }
}
```

**401 Unauthorized**


```json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing authentication token",
    "trace_id": "trace_abc123"
  }
}
```

**403 Forbidden**


```json
{
  "error": {
    "code": "access_denied",
    "message": "Insufficient permissions",
    "trace_id": "trace_abc123"
  }
}
```