Count Organizations API

Use this endpoint when you only need the number of matching organizations, not the full company records.

It uses the same filtering query structure as api/v3/organizations/.

Endpoint

POST https://api.vainu.io/api/v3/organizations/count/

📘

TIP: Reuse your tested Query Language snippets from Organizations API directly in this endpoint.

Request body

The count endpoint uses the same main query components as Organizations API:

query: Filtering query (Vainu query language) [REQUIRED if list is not set]

database: Country database (FI, SE, NO, DK,NL) [REQUIRED if list is not set]

async: default (True).

list (Optional) Query and database from Vainu list referenced is used. If you include query in the payload that will be used instead of query defined in the list.

recount_if_cache_max_ageIf the age of the count exceeds the max_age, a new count is triggered to refresh the cache.

• recount_if_cache_max_age + async: true: The API returns immediately with the previous count, but the recount is started in the background. You can poll the API with same payload until status:readyto get the fresh count.
• recount_if_cache_max_age + async: false: The API request waits for the recount to complete if needed and returns it

recount true/false. Force recount.

Test Count with Simple Example

We request the count of companies in Norway with Revenue more or equal than 1000000 NOK. If we have cached this count in the last 24h that number is returned immediately. If not API starts counting it synchronously.

async: Falsecount is started and returned with response.

payload = {
    "query": {"?GTE": {"financial_data.revenue": 1000000}},
    "database": "NO",
    "async": False,
    "recount_if_cache_max_age": 3600,
}
response = requests.post(
    organizations_count_end_point,
    headers={"Authorization": f"Bearer {access_token}"},
    json=payload,
)
print(response().json()['count']
# 180086

Utilize caches for faster responses with async: True

For faster responses, utilize cached counts with same query shape using async: True.

This feature was designed to meet user expectations for speed in real-time interfaces. API always responds instantly. If a pre-calculated count is found it is returned. If calculated count is not found count is started as a background process.

"recount_if_cache_max_age": 3600,We will start the a recount in the background if timeof count in the cache is older than 24h. But the previous count is returned right away.

Example:

Here we get the result that was counted 2 minutes ago and returned immediately, but at the same time a fresh count is started in the background. To get the latest count poll this same API with same payload until status is ready.

# Count of companies in Norway with revenue +1000000 NOK:
payload = {
    "query": {"?GTE": {"financial_data.revenue": 1000000}},
    "database": "NO",
    "async": True,
    "recount_if_cache_max_age": 3600,
}
response = requests.post(
    organizations_count_end_point,
    headers={"Authorization": f"Bearer {access_token}"},
    json=payload,
)
print(response().json()
# Example response:
"""
{
   'count': 180086,
   'duration': 164.5,
   'eta_utc': '2026-04-16T15:29:27.535137',
   'rate_of_change': None,
   'status': 'scheduled',
   'time': '2026-04-16T15:21:16.445551'
}
"""

Response fields

• count: Count result when available
• time: Timestamp for response
• status: Processing state (error process ready scheduled)
• duration: Duration of the count last time it was performed at time
• rate_of_change: how many items the count is changed by each second since two previous counts
• eta_utc: Optional estimated completion timestamp based on latest duration

Authentication

Refer to Authentication Overview

Python: Get count companies in a Vainu list

Use list field in payload. Database or query are not required to be set in this case. recount_if_cache_max_age cache is used if count in cache is newer than 24h. This makes the count faster when cache is hit.

import os
import requests

organizations_endpoint = "https://api.vainu.io/api/v3/organizations/"
organizations_count_endpoint = organizations_endpoint + "count/"
get_access_token_url = "https://api.vainu.io/api/token_authentication/refresh/"

refresh_token = os.environ["VAINU_REFRESH_TOKEN"]
access_token = requests.post(get_access_token_url, {"refresh": refresh_token}).json()["access"]
LIST_ID = "123abc-CHANGEME"

payload = {
    "list": LIST_ID,
    "async": False,
    "recount_if_cache_max_age": 3600,
}

response = requests.post(
    organizations_count_endpoint,
    headers={"Authorization": f"Bearer {access_token}"},
    json=payload,
)

print(response.json())

Example response

The response can include processing metadata when the count task is scheduled. Here this count was available in the cache. Count was started in the background and it will be soon available. You can poll the count end point with the same payload until status: ready

{
  "count": null,
  "time": "2026-04-01T13:17:33.280765",
  "status": "scheduled",
  "duration": null,
  "rate_of_change": null,
  "eta_utc": null
}

Notes and best practices

• Keep your query identical between count and organizations calls to compare expected dataset size before data fetch.
• For large or complex filters use async:Truefor faster responses and to avoid 2 minute synchronous timeout
• Reuse your tested Query Language snippets from Organizations API directly in this endpoint.
• Count endpoint does not need fields, limit, or offset because only count metadata is returned.