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

# List Users

> Retrieve a list of all students who are ambassadors in your programs

Retrieve a list of all students who are ambassadors in your programs. This endpoint supports filtering and pagination to help you manage large directories of student ambassadors.

## Overview

The List Users endpoint returns a paginated list of all student ambassadors enrolled in your referral programs. Use this endpoint to:

* View all ambassadors across your programs
* Filter ambassadors by program
* Implement pagination for large datasets
* Build dashboards showing ambassador statistics

## Authentication

This endpoint requires authentication using a Bearer token in the Authorization header:

```bash theme={null}
Authorization: Bearer sk_your_secret_key_here
```

## Query Parameters

<ParamField body="programId" type="string" required={false}>
  Filter results to only include users from a specific program. This is useful when you want to see ambassadors for a particular program.

  **Example:** `programId=prog_123abc`
</ParamField>

<ParamField body="limit" type="integer" default="50" required={false}>
  Maximum number of results to return per page. The default is 50, and the maximum is typically 100. Use this parameter along with `offset` to implement pagination.

  **Example:** `limit=25` returns 25 users per page
</ParamField>

<ParamField body="offset" type="integer" default="0" required={false}>
  Number of results to skip before starting to return results. Use this for pagination - if you're on page 2 with a limit of 50, set offset to 50.

  **Example:** `offset=50` skips the first 50 results
</ParamField>

## Request Example

<RequestExample>
  ```bash theme={null}
  curl -X GET "https://vantio.app/api/v1/users?programId=prog_123abc&limit=25&offset=0" \
    -H "Authorization: Bearer sk_your_secret_key_here"
  ```
</RequestExample>

## Response

The API returns a JSON object containing an array of user objects:

<ResponseField name="users" type="array" required>
  Array of user objects, each containing information about a student ambassador.
</ResponseField>

Each user object in the array contains:

<ResponseField name="id" type="string" required>
  Unique identifier for the user (student ambassador).
</ResponseField>

<ResponseField name="first_name" type="string" required>
  First name of the student ambassador.
</ResponseField>

<ResponseField name="last_name" type="string" required>
  Last name of the student ambassador.
</ResponseField>

<ResponseField name="email" type="string" required>
  Email address of the student ambassador.
</ResponseField>

<ResponseField name="program_id" type="string" required>
  ID of the program this user belongs to.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the user was created.
</ResponseField>

## Response Example

<ResponseExample>
  ```json theme={null}
  {
    "users": [
      {
        "id": "user_123abc",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "program_id": "prog_123abc",
        "created_at": "2024-01-15T10:30:00Z"
      },
      {
        "id": "user_456def",
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane.smith@example.com",
        "program_id": "prog_123abc",
        "created_at": "2024-01-16T14:20:00Z"
      }
    ]
  }
  ```
</ResponseExample>

## Pagination

To paginate through results, use the `limit` and `offset` parameters:

**Page 1 (first 50 users):**

```
GET /api/v1/users?limit=50&offset=0
```

**Page 2 (next 50 users):**

```
GET /api/v1/users?limit=50&offset=50
```

**Page 3 (next 50 users):**

```
GET /api/v1/users?limit=50&offset=100
```

Continue incrementing the `offset` by the `limit` value for each subsequent page.

## Error Responses

<ResponseField name="401" type="object">
  **Unauthorized** - Invalid or missing API key

  ```json theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseField>

## Use Cases

### Building an Ambassador Dashboard

Use this endpoint to fetch all ambassadors and display them in a dashboard:

```javascript theme={null}
async function fetchAllAmbassadors(programId) {
  const response = await fetch(
    `https://vantio.app/api/v1/users?programId=${programId}&limit=100`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  const data = await response.json();
  return data.users;
}
```

### Implementing Pagination

For large datasets, implement pagination to improve performance:

```javascript theme={null}
async function fetchUsersPage(page = 1, pageSize = 50) {
  const offset = (page - 1) * pageSize;
  const response = await fetch(
    `https://vantio.app/api/v1/users?limit=${pageSize}&offset=${offset}`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }
  );
  
  return await response.json();
}
```

## Best Practices

1. **Use pagination** - Always use `limit` and `offset` for large datasets to avoid timeouts
2. **Filter by program** - Use `programId` to narrow results when you only need users from specific programs
3. **Cache results** - User lists don't change frequently, so consider caching responses
4. **Handle errors** - Always check for 401 errors and prompt users to refresh their API key

## Rate Limits

This endpoint is subject to rate limiting. Check the response headers for rate limit information:

* `X-RateLimit-Limit` - Maximum requests allowed
* `X-RateLimit-Remaining` - Remaining requests in current window
* `X-RateLimit-Reset` - Time when the rate limit resets


## OpenAPI

````yaml GET /api/v1/users
openapi: 3.0.0
info:
  title: Vantio API
  version: 1.0.0
  description: >-
    Public v1 API. Authenticate using your secret key in the Authorization
    header: "Bearer sk_...".
servers:
  - url: http://localhost:3000
security:
  - bearerAuth: []
tags:
  - name: Users
    description: Student directory within your programs
  - name: Referrals
    description: Signups and conversions
  - name: Posters
    description: Ambassador posters and placements
  - name: Impressions
    description: QR scans and related activity
  - name: Earnings
    description: Earnings from referrals
paths:
  /api/v1/users:
    get:
      tags:
        - Users
      summary: List users (students) in your programs
      description: Retrieve a list of all students who are ambassadors in your programs
      parameters:
        - in: query
          name: programId
          schema:
            type: string
          description: Filter by program ID
        - in: query
          name: limit
          schema:
            type: integer
            default: 50
          description: Maximum number of results to return
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
          description: Number of results to skip
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
        '401':
          description: Unauthorized - Invalid or missing API key
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````