# List clients

> `GET` `/v1/clients`

URL: https://www.agencytitan.com/docs/tag/clients/GET/v1/clients

Operation ID: `clients_list`

Tag: [clients](https://www.agencytitan.com/docs/tag/clients.md)

## Description

Returns a paginated list of clients for your agency. Supports free-text search over client name and email, sorting, and filtering by client profile, status, priority level, tags, and assigned users. Repeat an array filter parameter to match any of several values (e.g. `?status=active_client&status=lead`). Deleted clients are excluded. Rows carry system fields plus `field_values.client_name` only; request additional custom field values with the `fields` parameter, or use Get a client for the complete record.

## Parameters

- `assigned_to` (query, optional, `array<string>`) — Only return clients assigned to at least one of these user ids (see List users). Optional filter. Omit unless the user asked for it; never guess identifiers.
- `fields` (query, optional, `array<string>`) — Custom field keys to include in `field_values` on each row (see List custom field definitions for the available keys). `client_name` is always included. Comma-…
- `limit` (query, optional, `integer`) — Maximum number of items to return (1-200).
- `offset` (query, optional, `integer`) — Number of items to skip before collecting the result set.
- `order` (query, optional, `string`) — Sort direction. Default `desc`.
- `priority_level` (query, optional, `array<string>`) — Only return clients whose priority level matches one of these values. Optional filter. Omit unless the user asked for it; never guess identifiers.
- `profile_id` (query, optional, `string`) — Only return clients belonging to this client profile. Optional filter. Omit unless the user asked for it; never guess identifiers.
- `search` (query, optional, `string`) — Free-text search filter.
- `sort` (query, optional, `string`) — Field to sort by. Default `created_at`.
- `status` (query, optional, `array<string>`) — Only return clients whose status matches one of these values (see the profile's status_options). Optional filter. Omit unless the user asked for it; never gues…
- `tags` (query, optional, `array<string>`) — Only return clients carrying at least one of these tags. Optional filter. Omit unless the user asked for it; never guess identifiers.

## Request body

_None_

## Responses

- `200` (`application/json`): Successful response.
  - Type: `object`
  - Properties:
    - `data` (`array<object>`, required)
    - `pagination` (`object`, required)
- `400` (`application/json`): Request validation failed (unknown or out-of-range parameters/properties are rejected).
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `401` (`application/json`): Missing, invalid, expired, or revoked bearer token.
  - Type: `object`
  - Properties:
    - `error` (`string`, required)
    - `error_description` (`string`, required)
- `403` (`application/json`): The authenticated user does not have permission for this operation.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `404` (`application/json`): The requested resource was not found.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `429` (`application/json`): Per-tenant rate limit exceeded (600 requests/minute across all /v1 REST endpoints). The Retry-After header indicates how many seconds to wait.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)
- `500` (`application/json`): An unexpected internal error occurred.
  - Type: `object`
  - Properties:
    - `error` (`object`, required)

## Authentication

- `bearerAuth` — http (bearer) — All /v1 endpoints (except `/v1/openapi.json` and `/v1/llms.txt`) require a bearer token. Two equal first-class paths: (1) an OAuth 2.0 access token from the au…

## Useful links

- Interactive page: https://www.agencytitan.com/docs/tag/clients/GET/v1/clients
- API reference home: https://www.agencytitan.com/docs/
- Tag page: https://www.agencytitan.com/docs/tag/clients.md
- This operation as Markdown: https://www.agencytitan.com/docs/tag/clients/GET/v1/clients.md
- OpenAPI JSON: https://www.agencytitan.com/docs/openapi.json
- Full API Markdown: https://api.agencytitan.com/v1/llms.txt
- API keys: https://app.agencytitan.com/settings/api-mcp