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

# list-identities

> List all identities in your Unkey workspace using the CLI. Retrieve paginated results with metadata and linked key counts for each entity.

Get a paginated list of all identities in your workspace. Returns metadata and rate limit configurations.

Perfect for building management dashboards, auditing configurations, or browsing your identities.

**Required permissions:**

* `identity.*.read_identity` (to list identities in your workspace)

<Note>
  See the [API reference](/api-reference/identities/list-identities) for the full HTTP endpoint documentation.
</Note>

## Usage

```bash theme={"theme":"kanagawa-wave"}
unkey api identities list-identities [flags]
```

## Flags

<ParamField body="--limit" type="integer">
  The maximum number of identities to return in a single request. Use this to control response size and loading performance. Must be between 1 and 100. Defaults to 100.
</ParamField>

<ParamField body="--cursor" type="string">
  Pagination cursor from a previous response. Use this to fetch subsequent pages of results when the response contains a cursor value.
</ParamField>

## Global Flags

| Flag         | Type   | Description                                              |
| ------------ | ------ | -------------------------------------------------------- |
| `--root-key` | string | Override root key (`$UNKEY_ROOT_KEY`)                    |
| `--api-url`  | string | Override API base URL (default: `https://api.unkey.com`) |
| `--config`   | string | Path to config file (default: `~/.unkey/config.toml`)    |
| `--output`   | string | Output format. Use `json` for raw JSON                   |

## Examples

<CodeGroup>
  ```bash Basic theme={"theme":"kanagawa-wave"}
  unkey api identities list-identities
  ```

  ```bash Limit results theme={"theme":"kanagawa-wave"}
  unkey api identities list-identities --limit=50
  ```

  ```bash Paginate with cursor theme={"theme":"kanagawa-wave"}
  unkey api identities list-identities --limit=50 --cursor=cursor_eyJrZXkiOiJrZXlfMTIzNCJ9
  ```

  ```bash JSON output for scripting theme={"theme":"kanagawa-wave"}
  unkey api identities list-identities --limit=10 --output=json
  ```
</CodeGroup>

## Output

Default output shows the request ID with latency, followed by the list of identities:

```text theme={"theme":"kanagawa-wave"}
req_01H9TQPP77V5E48E9SH0BG0ZQX (took 120ms)

{
  "identities": [
    {
      "id": "id_01H9TQP8NP8JN3X8HWSKPW43JE",
      "externalId": "user_123",
      "meta": {
        "name": "Alice Smith",
        "plan": "premium"
      },
      "ratelimits": [
        {
          "name": "requests",
          "limit": 1000,
          "duration": 60000
        }
      ]
    },
    {
      "id": "id_02ZYR3Q9NP8JM4X8HWSKPW43JF",
      "externalId": "user_456",
      "meta": {
        "name": "Bob Johnson",
        "plan": "basic"
      },
      "ratelimits": [
        {
          "name": "requests",
          "limit": 500,
          "duration": 60000
        }
      ]
    }
  ],
  "cursor": "cursor_eyJsYXN0SWQiOiJpZF8wMlpZUjNROU5QOEpNNFg4SFdTS1BXNDNKRiJ9",
  "total": 247
}
```

With `--output=json`, the full response envelope is returned:

```json theme={"theme":"kanagawa-wave"}
{
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQX"
  },
  "data": {
    "identities": [
      {
        "id": "id_01H9TQP8NP8JN3X8HWSKPW43JE",
        "externalId": "user_123",
        "meta": {
          "name": "Alice Smith",
          "plan": "premium"
        },
        "ratelimits": [
          {
            "name": "requests",
            "limit": 1000,
            "duration": 60000
          }
        ]
      }
    ],
    "cursor": "cursor_eyJsYXN0SWQiOiJpZF8wMlpZUjNROU5QOEpNNFg4SFdTS1BXNDNKRiJ9",
    "total": 247
  }
}
```