# User Events

Collects and ingests user events from Vercel, providing visibility into activities and actions within your Vercel organization.

**Sync Type: Incremental**

## Details

This input collects user events from the Vercel Events API. It supports incremental sync with automatic pagination and handles rate limiting. The input tracks the last processed event timestamp to ensure only new events are collected on subsequent runs. Key features include:

- Incremental sync with state management
- Rate limiting compliance (60 requests per second)
- Configurable lookback period for initial sync
- Optional payload inclusion for detailed event data

## Prerequisites

1. A Vercel account with appropriate permissions
2. A Vercel API access token with the necessary scopes
3. Organization permissions to access audit events

## Setup Instructions

1. **Navigate to Vercel Account Settings**:
   - Go to [Vercel Dashboard](https://vercel.com/dashboard)
   - Click on your profile/avatar in the top right
   - Select **Settings** from the dropdown menu

2. **Create Access Token**:
   - In the left sidebar, click **Tokens**
   - Click **Create Token**
   - Provide a descriptive name (e.g., "Monad User Events Connector")
   - Select the appropriate scope:
     - **Team**: Select the team/organization you want to monitor
     - **Expiration**: Choose an appropriate expiration period or set to never expire
   - Click **Create Token**

3. **Copy the Token**:
   - Copy the generated token immediately (it won't be shown again)
   - Store it securely for use in the Monad configuration

**Important**: Store the access token securely and never commit it to version control.

## Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

### Settings

| Setting        | Type    | Required | Default | Description                                                                                                                                             |
| -------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| With Payload   | boolean | Yes      | false   | Whether to include detailed payload information in the events. When enabled, provides additional context and data for each event                        |
| Backfill Start Time | string | No | The date to start fetching data from. If not specified, no past records will be fetched. |
| API Rate Limit | object | No | - | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |


### Secrets

| Secret       | Type   | Required | Description                                                 |
| ------------ | ------ | -------- | ----------------------------------------------------------- |
| Access Token | string | Yes      | The Vercel API access token with permissions to read events |

## How It Works

The Vercel User Events input operates with the following behavior:

### Initial Sync
- **First run**: Collects events from the specified number of lookback hours before the current time
- Uses the `lookback_hours` setting to determine how far back to retrieve historical events
- Processes events in chronological order to establish the baseline state

### Incremental Sync
- **Subsequent runs**: Collects only new events since the last successful run
- Maintains state with the timestamp of the last processed event

### Rate Limiting and Pagination
- Respects Vercel's API rate limits with built-in throttling (60 requests per second)
- Automatically handles pagination to retrieve all available events
- Processes up to 100 events per API request for optimal performance

## Troubleshooting

Common issues and their solutions:

### Authentication Issues
1. **Invalid token error**
   - Verify the access token is correct and hasn't expired
   - Ensure the token has the necessary permissions for your organization
   - Check that the token hasn't been revoked or regenerated

2. **Insufficient permissions**
   - Verify your account has access to the organization's events
   - Ensure the token was created with appropriate team/organization scope
   - Contact your Vercel organization admin if you lack permissions

### Connection Problems
1. **Rate limiting**
   - The input automatically handles rate limiting with appropriate delays
   - If persistent rate limit issues occur, consider reducing collection frequency
   - Monitor your organization's overall API usage

### Data Collection Issues
1. **Missing events**
   - Verify the lookback hours setting is appropriate for your needs
   - Check that events exist in the specified time range
   - Ensure your token has access to all relevant teams/projects

2. **Duplicate events**
   - The input maintains state to prevent duplicates during incremental sync
   - If duplicates occur, check for configuration changes between runs
   - Verify the state storage is functioning correctly

### Configuration Problems
1. **Payload settings**
   - The "With Payload" setting affects the amount of data collected
   - Enable payload for detailed analysis but consider the increased data volume
   - Disable payload for basic event tracking to reduce bandwidth usage

## Related Articles

- [Vercel User Events API Documentation](https://vercel.com/docs/rest-api/reference/endpoints/user/list-user-events)
- [Vercel API Authentication](https://vercel.com/docs/rest-api#authentication)
- [Managing Vercel Access Tokens](https://vercel.com/guides/how-do-i-use-a-vercel-api-access-token)

## Sample Record

```json
{
  "text": "You set username to parvdesai-monad",
  "entities": [
    {
      "type": "link",
      "start": 5,
      "end": 23
    }
  ],
  "createdAt": 1754955995004,
  "created": 1754955995004,
  "user": {
    "uid": "ed45db91-9c99-573a-7926-ca3713b984ca",
    "username": "parvdesai-company",
    "email": "parv.desai@monad.com",
    "avatar": "https://avatar.example.com/user.png"
  },
  "principal": {
    "uid": "3348a310-15fe-098e-a276-3dd8dcb748fc",
    "username": "john.doe-dev",
    "email": "sarah.wilson@tech.io",
    "avatar": "https://avatar.example.com/user.png"
  },
  "userId": "5cb24ca2-5417-3a59-dc86-b0fa2131c7c3",
  "principalId": "95910aea-efea-c08a-49d8-54fa059599f4",
  "id": "uev_GCIE87IgGt9Ulmf2eF6P7Hgu"
}
```