> ## 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

> Read and change your Vollna data from your own code

The Vollna API reads and changes your Vollna data from your own code: filters and their jobs, the AI qualifier, proposal templates, proposals and their outcomes, auto-bidding, Market Insights and your Upwork profiles.

> [!NOTE]
>
> API access is included with the **Agency** plan and with an Agency trial. On an active
> paid plan that does not include it, the account owner or an admin can add it for
> **\$10/month** from [API Tokens](https://www.vollna.com/dashboard/team/api-tokens) in
> the dashboard.
>
> A trial gets 50 project credits to evaluate the API — see [Credit System](#credit-system).
> Endpoints that return your own data (proposals, invitations, profiles, auto-bidding setups) use no credits.

## 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]
>
> All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

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

## Who the token acts as

An API token belongs to a team. It acts as the team owner and sees what the owner sees in that team. Some settings belong to one person: hidden jobs, saved Market Insights searches and the proposal template of a filter's job cards. Through the API, these are the owner's.

Every write takes effect at once. There is no preview step.

## Rate Limiting

The Vollna API allows 30 requests per minute. The limit applies per subscription, so all API tokens of a team share it.

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

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

## Daily caps

Some reads take more work on Vollna's side. Each has a daily cap. The API and [MCP](https://www.vollna.com/docs/mcp/introduction.md) count against the same caps, per subscription. The caps reset at 00:00 UTC.

| Cap | Endpoints | Default per day |
| - | - | - |
| `explain_job` | `GET /filters/{id}/explain` | 100 |
| `filter_preview` | `POST /filters/{id}/preview` | 100 |
| `keyword_suggestions` | `POST /filters/keyword-suggestions` | 20 |
| `market_insights` | `GET /market-insights` | 50 |
| `niche_difficulty` | `GET /market-insights/niche-difficulty`, `GET /projects/{id}/competition` | 50 |
| `keyword_opportunities` | `GET /market-insights/keyword-opportunities` | 20 |
| `diagnose` | `GET /insights/reply-diagnosis` | 20 |
| `instructions_generation` | Template instruction drafts through MCP | 10 |

Your plan can set other values. `GET /usage` returns each cap with what is used and when it resets, under `mcpDaily`.

When a cap is used up, the API returns a 429 status code:

```json theme={null}
{
  "error": "Limit reached",
  "message": "Your team used today's 100 job explanations. The count resets at 00:00 UTC."
}
```

## 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`
* `GET /filters/{id}/verdicts`
* `POST /filters/{id}/preview`, for its sample jobs
* `GET /auto-bidding/jobs`
* `GET /auto-bidding/jobs/{id}`

Jobs an app reads through [MCP](https://www.vollna.com/docs/mcp/introduction.md) use the same credits.

A project costs 1 credit the first time it is returned in a billing period. Paging through the same
projects again costs nothing.

Allocations:

| Plan | Project credits |
| - | - |
| Agency (paid) | 10,000 per month |
| Any paid plan with the API add-on | 10,000 per month |
| Agency trial | 50 for the trial |

Paid plans can top up beyond their monthly allocation from the dashboard. A trial allocation is a
fixed ceiling and cannot be topped up.

Each successful response from the first three endpoints above includes a `credits` object, so you can track usage in real time. The other endpoints do not return it. Read the balance with `GET /usage`.

```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",
  "message": "No project credits remain for the current period.",
  "credits_needed": 20,
  "credits_remaining": 0,
  "credits_reset_date": "2024-04-01T00:00:00Z"
}
```

Requests are all-or-nothing: a page wider than your remaining balance is refused without consuming
anything. When `credits_remaining` is above zero, lower the `limit` parameter to fit the balance —
`message` names both numbers.

The other endpoints that use credits answer 402 with `error` and `message` only. They answer the same way when a plan limit such as the number of filters is reached:

```json theme={null}
{
  "error": "Plan limit reached",
  "message": "Your team has 3 project credits left for this period and this page needs 5. Each job returned through the API or MCP uses one credit; credits reset on 2026-11-01."
}
```

## AI Qualifier verdicts

`GET /filters/{id}/projects` and `GET /results/{id}/projects` return the filter's AI Qualifier
verdict for each job in a `qualification` object:

```json theme={null}
{
  "title": "Laravel developer for a booking platform",
  "qualification": {
    "status": "qualified",
    "reason": "Client has spent $103,580 and the job matches the Laravel work you asked for.",
    "processedAt": "2026-08-20T11:04:31+00:00"
  }
}
```

`qualification` is `null` when the filter has no qualifier, or when the job has not been qualified
yet. The key is always present, so you can read it without checking first.

| `status` | Meaning |
| - | - |
| `qualified` | The job passed your qualifier prompt |
| `disqualified` | The job failed it |
| `pending`, `processing` | The verdict is still being decided, poll again |
| `error` | The qualification failed |
| `skipped` | It was not run, because there were no AI Qualifier credits or no qualifier configured at the time |

`reason` and `processedAt` are `null` until a verdict is decided.

Reading a verdict costs no AI Qualifier credits. Only running a qualification does, and these
endpoints never run one: a job carries a verdict here once it was qualified in the dashboard, or by
the filter's automatic mode.

## 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"
}
```

Most endpoints also send `message`, which says what to do next. When fields fail validation, `fields` names each one:

```json theme={null}
{
  "error": "Validation failed",
  "message": "Some fields are not valid. name: Give a name of 1 to 255 characters.",
  "fields": {
    "name": "Give a name of 1 to 255 characters."
  }
}
```

## 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, project API credits are depleted, or a plan limit is reached |
| 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 or a daily cap (see Rate Limiting and Daily caps) |
| 500 | Internal Server Error | The request failed due to a server error |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.