Limitations
This article explains the limitations on the TextReveal API.
Max supported entities (companies/concepts) in a single request
The recommended maximum number of entities requested in a single request is 5 000. This limit applies to both /analyze/dataset and /analyze/tql routes.
If you have more entities to request at the same time you need to cut and create two or more requests.
Time range limitations
The recommended maximum time range for an instance is one year to avoid overly heavy results. However, it is possible to parallelize analyses over multiple years (see limitations on simultaneous instances below). This approach allows faster data retrieval since the time range is queried month by month sequentially.
A longer time range results in slower data retrieval because it relies on a single cluster processing data sequentially. In contrast, shorter time ranges can be parallelized across multiple clusters, enabling faster retrieval as payloads are processed simultaneously.
Automatic deletion of documents / Max TTL for analyzes
Our documents are automatically deleted after 2 weeks (1209600 seconds).
This deletion cannot be canceled.
Max simultaneous running instances
The maximum number of simultaneous running instances per company is set to 10. If this limit is reached, the instances will be queued and the status of the related instances will be set to pending.
Max simultaneous pending instances
The maximum number of simultaneous pending instances per company is set to 60. If this limit is reached, the TextReveal® API will throw an error with the 429 status code (TOO MANY REQUESTS).
Data access limitations
The access to premium document's texts is forbidden. However, all other fields remain accessible.
Depending on the route, the text field will either be replaced by the message "The download of licensed text is not allowed" or an error field indicating the reason.
Rate limiting
To ensure fair usage and protect the service, the TextReveal® API enforces a request rate limit per client. The limit is counted independently for each API key or token, over a sliding window of 300 seconds (5 minutes).
| Authentication method | Header used | Limit |
|---|---|---|
| API key | x-api-key | 300 requests / 5 min (~1 req/s) |
| JWT token | Authorization: Bearer <jwt> | 15 000 requests / 5 min (~50 req/s) |
| Unauthenticated | (none) | 300 requests / 5 min per IP address |
These values are ceilings that should not be exceeded. Because enforcement relies on a sliding window, you should treat each limit as a maximum sustained rate rather than a guaranteed per-request quota.
This rate limit is independent from the 429 returned when too many analysis instances run at the same time (see Max simultaneous pending instances above).
Exceeding the rate limit
When the limit is exceeded, the API responds with the HTTP status 429 Too Many Requests. The body follows our normalized error format:
{
"message": "API rate limit exceeded. Please retry later.",
"code": 429,
"reason": "too_many_requests"
}The following headers are returned on a 429 response:
| Header | Value |
|---|---|
RateLimit-Limit | The applicable limit (300 or 15000) |
RateLimit-Remaining | 0 |
RateLimit-Reset | 300 (seconds before the window resets) |
When you receive a 429, wait before retrying and apply a back-off strategy based on the RateLimit-Reset header, which indicates the number of seconds before the rate limit window resets.