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

# User List API

> Retrieve a paginated list of users in your organization

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

## Request

**Content-Type:** `application/json`

### Query Parameters

| Parameter | Type    | Required | Description                                                      |
| --------- | ------- | -------- | ---------------------------------------------------------------- |
| `name`    | string  | No       | Filter users by name (partial match). Min 1, Max 100 characters. |
| `limit`   | integer | No       | Number of records to return. Min 1, Max 100.                     |
| `cursor`  | string  | No       | Cursor for pagination. Default 0.                                |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.pazy.io/v1.0/users?limit=30" \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const params = new URLSearchParams({ limit: '30' });
  const response = await fetch(`https://api.pazy.io/v1.0/users?${params}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    }
  });

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

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/users"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }
  params = { "limit": 30 }

  response = requests.get(url, headers=headers, params=params)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                     | Type    | Description                                     |
| ------------------------- | ------- | ----------------------------------------------- |
| `ok`                      | boolean | Indicates whether the request was successful    |
| `data`                    | object  | Contains the user list response data            |
| `data.users`              | array   | List of users                                   |
| `data.users[].id`         | string  | Unique identifier for the user                  |
| `data.users[].name`       | string  | Full name of the user                           |
| `data.context`            | object  | Pagination metadata                             |
| `data.context.hasMore`    | boolean | Indicates whether there are more users to fetch |
| `data.context.nextCursor` | number  | Cursor to fetch the next page                   |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "users": [
      {
        "id": "<userId>",
        "name": "John Doe"
      },
      {
        "id": "<userId>",
        "name": "Jane Smith"
      }
    ],
    "context": {
      "hasMore": true,
      "nextCursor": 30
    }
  }
}
```

## Error Responses

### Validation Error

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /query/limit: must be <= 100"
  }
}
```

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Internal Error

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}
```

## Best Practices

* Use the `id` returned for a user as the input to the [User Details API](/apis/user-details) for full user information
* Use `name` to narrow down results — partial matching is supported (e.g., `John` matches `John Doe`, `Johnny`)
* Use `cursor` and `limit` together to paginate; `nextCursor` from the response can be used as the `cursor` value for the next call