> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Customers

> Retrieve a paginated list of customer accounts with optional filtering and sorting

Retrieves a paginated list of all customer accounts. You can filter and sort the results using query parameters.

## Query Parameters

<ParamField query="page" type="integer" default="1">
  The page number to retrieve (1-indexed).
</ParamField>

<ParamField query="limit" type="integer" default="10">
  The number of customers to return per page. Must be one of: `5`, `10`, `25`, `50`, or `100`. Values exceeding `100` are capped automatically.
</ParamField>

<ParamField query="filters" type="string">
  A JSON-encoded array of filter objects. Each filter object has the following properties:

  <Expandable title="Filter Object">
    <ParamField body="field" type="string" required>
      The field to filter on. Supported fields:

      | Field                      | Operators  | Description                                                      |
      | -------------------------- | ---------- | ---------------------------------------------------------------- |
      | `sales_owner_id`           | `eq`, `in` | The sales owner user ID                                          |
      | `csm_id`                   | `eq`, `in` | The customer success manager user ID                             |
      | `tag_ids`                  | `in`       | Tag IDs associated with the account                              |
      | `has_active_subscriptions` | `eq`       | Whether the account has active subscriptions (`true` or `false`) |
      | `integration_ids`          | `in`       | External integration IDs linked to the account                   |
    </ParamField>

    <ParamField body="operator" type="string" required>
      The comparison operator.

      | Operator | Description                                 |
      | -------- | ------------------------------------------- |
      | `eq`     | Exact match                                 |
      | `in`     | Matches any value in a comma-separated list |
    </ParamField>

    <ParamField body="value" type="string" required>
      The value to match against. For the `in` operator, use comma-separated values.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField query="sort" type="string">
  Sort specification in `field:order` format. Order is either `asc` (ascending) or `desc` (descending).

  Sortable fields: `name`.
</ParamField>

<ParamField query="search" type="string">
  Search customers by name.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.alguna.io/accounts?page=1&limit=25" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (with filters and sort) theme={null}
  curl -G "https://api.alguna.io/accounts" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode 'page=1' \
    --data-urlencode 'limit=10' \
    --data-urlencode 'filters=[{"field":"has_active_subscriptions","operator":"eq","value":"true"}]' \
    --data-urlencode 'sort=name:asc'
  ```

  ```javascript Node.js theme={null}
  const customers = await alguna.accounts.list({
    page: 1,
    limit: 25,
    filters: [
      { field: "has_active_subscriptions", operator: "eq", value: "true" }
    ],
    sort: "name:asc"
  });
  ```
</RequestExample>

## Response

<Snippet file="list-accounts.mdx" />

<ResponseField name="pageCount" type="integer">
  Total number of pages available based on the current limit.
</ResponseField>

<ResponseField name="limit" type="integer">
  The number of items per page used for this request.
</ResponseField>