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

# Introduction

> Learn how to automate your Upwork workflow with Vollna API

Automate your entire Upwork workflow - discover new projects via your custom filters, track proposal analytics, manage invitations, and monitor Upwork profiles - all through one powerful API.

<Note>
  API access is included with the <strong>Agency</strong> plan.
</Note>

## Authentication

To use the Vollna API, you need to sign up for an account first. Follow these steps to obtain your API token:

1. Create an account at [vollna.com](https://www.vollna.com)
2. Go to your Dashboard
3. Click your profile menu (top-right)
4. Select "API Tokens"
5. Generate a new API token

<Warning>
  Your API token carries many privileges, so be sure to keep it secure! Do not share your API token in publicly accessible areas such as GitHub, client-side code, etc.
</Warning>

<Warning>
  All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
</Warning>

Include your API token in the `X-API-TOKEN` header with every request:

## Rate Limiting

The Vollna API implements rate limiting of 5 requests per minute. API rate limits are essential for managing server load and ensuring consistent and reliable service for all users. By limiting the number of requests a user can make per minute, it helps prevent any single user from overloading the system, which can lead to slower response times or system outages, ensuring fair usage and availability of the service for everyone.

When rate limits are exceeded, the API will return a 429 status code with the following response:

```json theme={null}
{
  "error": "Rate limit exceeded"
}
```

## Credit System

To ensure fair usage and prevent abuse of the API, we implement a credit-based system for certain endpoints. Each API request to retrieve projects consumes credits based on the number of projects returned. This system helps maintain service quality and prevents unauthorized data scraping.

Project credits are consumed on these endpoints:

* `GET /filters/{id}/projects`
* `GET /results/{id}/projects`
* `GET /projects/lookup`

<Note>
  The credit system is designed to accommodate normal business operations while preventing abuse. Most agencies will find their monthly credit allocation more than sufficient for their needs.
</Note>

Each successful response from the project-retrieval endpoints above includes a `credits` object, so you can track usage in real time:

```json theme={null}
{
  "credits": {
    "remaining": 9995,
    "reset_date": "2026-01-16T00:00:00+00:00",
    "new_projects_consumed": 5,
    "total_projects_returned": 20
  }
}
```

Your project credit allocation is individual per team subscription and visible in your dashboard at [https://www.vollna.com/dashboard/team/api-tokens](https://www.vollna.com/dashboard/team/api-tokens).

When credits are depleted, the API will return a 402 status code with the following response:

```json theme={null}
{
  "error": "Insufficient credits",
  "credits_remaining": 0,
  "credits_reset_date": "2024-04-01T00:00:00Z"
}
```

## Common Response Formats

### Success Response

```json theme={null}
{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "pages": 5
  }
}
```

### Error Response

```json theme={null}
{
  "error": "Error message"
}
```

## Status Codes

Vollna uses standard HTTP response codes to indicate the success or failure of an API request.

In general:

* Codes in the 2xx range indicate success
* Codes in the 4xx range indicate an error that failed given the information provided

| Code | Name                  | Summary                                                                   |
| ---- | --------------------- | ------------------------------------------------------------------------- |
| 200  | OK                    | Everything worked as expected                                             |
| 400  | Bad Request           | The request was unacceptable, often due to missing a required parameter   |
| 401  | Unauthorized          | Invalid or missing API token provided in X-API-TOKEN header               |
| 402  | Payment Required      | Team subscription is inactive, or project API credits are depleted        |
| 403  | Forbidden             | The API token doesn't have permissions to perform the request             |
| 404  | Not Found             | The requested resource was not found                                      |
| 429  | Too Many Requests     | The request was rejected due to rate limiting (see Rate Limiting section) |
| 500  | Internal Server Error | The request failed due to a server error                                  |