Introduction

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.

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 in the dashboard.A trial gets 50 project credits to evaluate the API — see Credit System. Endpoints that return your own data (proposals, invitations, profiles, auto-bidding) 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:

Create an account at vollna.com
Go to your Dashboard
Click your profile menu (top-right)
Select “API Tokens”
Generate a new API token

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.

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:

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:

{
  "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

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.

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.

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

{
  "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. When credits are depleted, the API will return a 402 status code with the following response:

{
  "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.

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:

{
  "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

{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "pages": 5
  }
}

Error Response

{
  "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

API Reference

Profiles

Proposals

Invitations

Filters

Projects

Auto Bidding

Proposal Templates

Authentication

Rate Limiting

Credit System

AI Qualifier verdicts

Common Response Formats

Success Response

Error Response

Status Codes

​Authentication

​Rate Limiting

​Credit System

​AI Qualifier verdicts

​Common Response Formats

​Success Response

​Error Response

​Status Codes

Authentication

Rate Limiting

Credit System

AI Qualifier verdicts

Common Response Formats

Success Response

Error Response

Status Codes