Query and rate limits
The limits Elium applies to API queries and requests, how to read your query's cost in each response, and what to do when Elium refuses a request.
The Elium API has limits that protect the platform from queries and integrations that ask for too much. There are two kinds:
- Query limits: how much one query can ask for.
- Rate limits: how many requests an integration can send.
Normal use stays far below both. This page explains how to see how close a query is to its limits, and what to do when Elium refuses a request.
Query limits
Before a query runs, Elium measures it. A query that asks for too much is refused and does not run at all.
Check the extensions key
Every response has an extensions key next to data. Its complexity object gives three values for your query, and the maximum for each one. Here is the response to { me { id } }, the query from the quick start:
{
"data": {
"me": {
"id": "..."
}
},
"extensions": {
"complexity": {
"score": 2,
"depth": 3,
"resolvers": 1,
"max_score": 2000,
"max_depth": 15,
"max_resolvers": 1000
}
}
}
scoreestimates the work the query asks for. Fields that load other objects and long lists make it grow.depthcounts the levels of nesting in the query.resolverscounts the fields that load another object.
Read these values while you build a query, and keep each one under its maximum. A query above a maximum can be refused at any time, even if it works today.
These limits apply to queries. Mutations are not measured this way, but the rate limits below apply to them.
Page size
Lists use first or last to set the page size, from 1 to 100. Some filters that take a list of IDs, such as tags, also have a maximum. To get more items, paginate: ask for 100 items, then pass the cursor of the last item as after to get the next 100.
Fields that cost more
Most fields cost little. A few do heavy work on the server and raise the score much more than others:
- Questions to the AI, such as
me.answer.answer(query:). - Automatic translations of a story.
- Usage statistics of the platform, a space or a story.
Ask for these fields only when you need them. Send one AI question per request: to ask several questions, send several requests.
Rate limits
Elium can also limit how many requests an integration sends in a given time, and how many it sends at once. These limits apply to queries and mutations alike. Elium does not publish them, and they can change.
To stay under them:
- Send requests one after the other, not in parallel.
- Wait a moment between two mutations, especially when you create or edit many stories.
- Do not poll: do not send the same query in a loop to watch for changes. Read the data when you need it.
- Cache the results that do not change often, such as the list of spaces.
When Elium refuses a request
| Response | Cause | What to do |
|---|---|---|
HTTP 400, an error that names complexity, depth or resolvers | The query asks for too much | Change the query (see below). Sending it again gives the same error. |
| HTTP 400, an error that names an argument | An argument is above its maximum, such as first above 100 | Lower the value and paginate. |
| HTTP 429 | Too many requests | Wait, then send the request again. |
Fix a query that asks for too much
The error response still contains the extensions.complexity object, so you can see which value to lower. Then:
- Split the query into several smaller queries.
- Ask for fewer items in each list, and paginate.
- Remove the fields you do not use, especially AI, translation and statistics fields.
- Avoid nesting lists inside lists, such as the tags of every story of every space.
Retry after too many requests
When you get HTTP 429, stop sending requests for a while:
- If the response has a
Retry-Afterheader, wait at least that number of seconds. - If not, wait at least one minute.
- If the next request is refused again, wait longer each time, for example twice as long, and stop after a few tries.
Do not keep sending requests while Elium refuses them. They will be refused too, and Elium can block an integration that keeps trying.
Changes to these limits
Elium can change these limits at any time, without notice. Elium can also refuse a query, or block a token or an integration, if it puts the platform at risk. This can happen even when it stays under the limits on this page. If your integration needs more than these limits allow, contact Elium support before you build it.