---
updatedAt: 2026-10-02T09:51:31.000Z
agentTools:
  projectIndex: https://developers.vainu.com/llms.txt
---

# Vainu API Free Trial

Get started with Vainu API free trial

## Get a Free Trial Token

<Callout icon="➡️" theme="default">
  Request Vainu API Free Trial from [https://www.vainu.com/delivery-methods/api/](https://www.vainu.com/delivery-methods/api/)
</Callout>

The trial token is perfect for:

* Testing the API before purchasing
* Evaluating Vainu data for your use case
* Learning the API structure and capabilities
* Prototyping integrations

## JWT Authentication for Trial

### Get Access Token and Use It to Get Data

```shell Vainu CLI
# Install Vainu CLI https://developers.vainu.com/docs/vainu-cli
export VAINU_JWT_REFRESH_TOKEN='123...'   # your token free trial access token

# Simple example of using the APIv3 search endpoint:
vainu organizations-search \
  --search volvo \
  --database SE \
  --fields business_id,name,website \
  --limit 5

```
```python Vainu CLI Python API
import os
import pprint

from vainu_cli import VainuJWTSyncClient

# Set your free trial access token to env VAINU_JWT_REFRESH_TOKEN
# export VAINU_JWT_REFRESH_TOKEN=...
client = VainuJWTSyncClient(refresh_token=os.environ["VAINU_JWT_REFRESH_TOKEN"])

payload = {
    "search": "volvo",
    "fields": ["business_id", "name", "website"],  # Any APIv3 fields from https://vainu.app/data-catalogue/
    "database": "SE",
    "limit": 5,
}

pprint.pprint(client.organizations_search(payload))
client.close()
```
```python
"""Simple example of using the APIv3 search endpoint.

Fuzzy text search that finds companies from a single input: business id,
company name or website. Results are sorted by relevance. The Vainu web
application search bar uses this same endpoint.

Set your free trial access token to env VAINU_JWT_REFRESH_TOKEN
export VAINU_JWT_REFRESH_TOKEN=...
"""

import os
import pprint

import requests

# Exchange the refresh token for a short-lived access token
response = requests.post(
    "https://api.vainu.io/api/token_authentication/refresh/",
    data={"refresh": os.environ["VAINU_REFRESH_TOKEN"]},
    timeout=10,
)
response.raise_for_status()
access_token = response.json()["access"]

payload = {
    "search": "volvo",
    "fields": ["business_id", "name", "website"],  # Any APIv3 fields from https://vainu.app/data-catalogue/
    "database": "SE",
    "limit": 5,
}

response = requests.post(
    "https://api.vainu.io/api/v3/organizations/search/",
    headers={"Authorization": f"Bearer {access_token}"},
    json=payload,
    timeout=10,
)
pprint.pprint(response.json())
# Example output:
# [{'business_id': 'SE5560125790',
#   'name': 'Aktiebolaget Volvo',
#   'website': 'https://www.volvogroup.com/se/'},
#  {'business_id': 'SE5560743089',
#   'name': 'Volvo Personvagnar Aktiebolag',
#   'website': 'volvocars.com/se'},
#  ...]
```

### Token Lifecycle

The access token is valid for **12 hours**. Refresh it when expired using the refresh token.

Reference [Authentication Overview](https://developers.vainu.com/docs/jwt-authentication)

## Trial Limitations

Trial tokens come with the following limitations:

| Feature                 | Trial API                     | Full API                                                            |
| ----------------------- | ----------------------------- | ------------------------------------------------------------------- |
| **Lifetime**            | 30 days                       | Unlimited                                                           |
| **Response limit**      | Max 20 results per request    | No limit.<br />Even full databases can be fetched.                  |
| **Endpoints**           | `/api/v3/organizations/` only | Full API access                                                     |
| **Concurrent requests** | 1 request at a time           | Up to 20 concurrent requests.<br />(Increasing concurrent requests) |
| **Rate limit**          | 1,000 requests per week       | Unlimited (tier-dependent)                                          |
| **Databases**           | Limited availability          | FI, SE, NO, DK, NL                                                  |

## Example: Trial API Call

Make your first API call with trial token:

```python
import requests

# 1. Get access token
REFRESH_TOKEN = "your_trial_refresh_token"
TOKEN_ENDPOINT = "https://api.vainu.io/api/token/refresh/"

token_resp = requests.post(TOKEN_ENDPOINT, json={"refresh": REFRESH_TOKEN})
access_token = token_resp.json()["access"]

# 2. Query companies
COMPANIES_ENDPOINT = "https://api.vainu.io/api/v3/organizations/"

payload = {
    "query": {"?EQ": {"industry_codes_local": ["62"]}},
    "database": "FI",
    "fields": ["business_id", "name", "domain"],
    "limit": 20  # Trial limit
}

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

response = requests.post(COMPANIES_ENDPOINT, headers=headers, json=payload)
companies = response.json()["results"]

print(f"Found {len(companies)} software companies:")
for company in companies:
    print(f"  - {company['name']} ({company['domain']})")
```

## Key Differences from Full API

### Response Limit

Trial: Maximum 20 results per request

```python
payload = {
    ...
    "limit": 20  # Max for trial
}
```

Full API: Up to full database exports

```python
payload = {
    ...
    "limit": 100000
}
```

\`

### Rate Limiting

Trial: 1,000 requests per week total

Full API: Up to 5 concurrent requests with higher weekly limits

### Concurrent Requests

Trial: 1 concurrent request only

```python
# ✓ Allowed
response1 = requests.post(ENDPOINT, ...)
result1 = response1.json()  # Wait for response

# ✗ Not allowed (won't start until previous completes)
response2 = requests.post(ENDPOINT, ...)
```

Full API: Up to 5 concurrent requests

## Upgrade from Trial

When ready to move to production:

1. Contact Vainu sales
2. Select appropriate pricing tier
3. Migrate to production API keys
4. Increase limits and get support

## Common Trial Errors

### Error: Rate Limit Exceeded

You've exceeded the 1,000 requests/week limit:

```
Status: 429 Too Many Requests
Error: Rate limit exceeded
```

**Solution:** Wait until next week or upgrade to full API.

### Error: Query Exceeds 20 Results

Your limit is 20 results:

```python
# Wrong - will fail
payload = {"limit": 100}

# Correct
payload = {"limit": 20}
```

### Error: Endpoint Not Available

Trial only supports `/api/v2/companies`:

```python
# Wrong - trial doesn't support this
endpoint = "https://api.vainu.io/api/v3/stats/"

# Correct - use v2
endpoint = "https://api.vainu.io/api/v3/organizations/"
```

## After Trial Expires

When your 30-day trial expires:

* Access tokens will become invalid
* New token refresh will fail
* You'll need to upgrade or request a new trial

Contact support if you need an extension.

## Getting Help

During your trial:

* Review API documentation in this guide
* Check code examples and best practices
* [Contact support](https://vainu.io/contact) with questions
* Join Community Vainu Community Slack

## Next Steps

* Explore [Authentication](https://developers.vainu.com/docs/authentication) methods
* Learn about [Filtering Query Language](https://developers.vainu.com/docs/filtering-query-language)
* Review [Getting Started](https://developers.vainu.com/docs/getting-started) guide
* Check [Organizations API](https://developers.vainu.com/docs/organizations-api) for search capabilities

***

Ready to get started? [Get your free trial token](https://api.vainu.io/get-access) now!