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).
Task limits
Only a limited number of tasks run at the same time, the others wait in a queue. AI Reports, exports and universe ESG reports each have their own queue, and they never delay each other. See Tasks for how these queues work.
| Task type | Requested with | Running at the same time | Waiting in the queue |
|---|---|---|---|
| Single-company AI Reports | Generate Report | 5 per client | Unlimited |
| Bulk AI Reports | Generate Report | 3 per client | Unlimited |
| Exports | Export Universe Entities | 5 per client | 5 per client |
| Universe ESG reports | Universes ESG Cases Report Universes ESG Events Report | 1 per client | 5 per client |
The AI Report queue is also shared across all clients using the platform, so a report can occasionally wait for a moment even if you are under your own limits. The export and universe ESG report queues only ever contain your own client's tasks.
Requesting more tasks than the "running at the same time" limit is never an error: the extra ones are created with the pending status and start automatically when one of your running tasks finishes.
A request is only refused when the queue for that task type has a maximum size and that maximum is reached. AI Reports have an unlimited queue, so they are never refused for this reason; exports and universe ESG reports accept 5 waiting tasks each.
When one of those two queues is full, the API responds with the HTTP status 429 Too Many Requests, and no task is created:
{
"message": "You already have 5 export tasks waiting in queue. Please wait for one to start before requesting a new one.",
"code": 429,
"reason": "too_many_requests"
}Wait for one of your queued tasks to start before requesting a new one. You can check where your tasks stand with GET /tasks.
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.