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

# List Account States

> Tier, owner, and discard flag for a set of accounts

Bulk read of [account state](/account-states) for a set of companies.
Companies with no state yet are simply absent from the result — every account
is queryable, and "no state" is a normal answer.

Tags are not part of this read. Fetch them per record with
[Get An Account's Tags](/api-reference/get-account-record-tags), or read the
vocabulary with [List Tag Groups](/api-reference/list-tag-groups).

## Query Parameters

<ParamField query="company_ids" type="string" required>
  Comma-separated or repeated company UUIDs. From `company_id` on [List
  Accounts](/api-reference/list-accounts). Required: a bare list-everything
  would be an unbounded scan.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.clustr-ai.com/api/public/account-states?company_ids=9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f,7a1b2c3d-4e5f-4061-8a2b-3c4d5e6f7081" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "account_states": [
        {
          "company_id": "9c4d5e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
          "tier_id": "1a2b3c4d-5e6f-4071-8a92-b3c4d5e6f708",
          "owner_id": "3f2b1c40-8a11-4f2e-9d61-0f5a8c7a2b13",
          "is_discarded": false,
          "notes": "",
          "updated_at": "2026-09-10T10:00:00Z",
          "updated_by": null
        }
      ]
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": { "message": "company_ids is required", "code": "BAD_REQUEST" }
  }
  ```
</ResponseExample>