- Docs
- API reference
- Endpoints and schemas
- GraphQL
The Enigma request lifecycle
The stages a GraphQL request goes through, in order, and what each one means for your integration.
Each GraphQL request goes through these stages in order. A request that fails stops at the stage that rejects it. Status codes, limits, and the response format are in API basics.
- 1AuthenticateChecks the API key
- 401Missing or invalid key
- 403Disabled key
- 2ValidateParses and checks the query
- 400Invalid query
- 3Rate limitSearches only, per key
- 429Over the limit
- 4ResolveCredits, match, connections, directives
- 400No credits
- 504Too slow
- 5RespondSets the status and headers
- 200Answer
- 400Partial answer
- 202, 206Background task
- 302Over 6 MB
- 6UsageRecorded after the response
1. Authenticate
Section titled “1. Authenticate”The API checks x-api-key on every request. The key sets your plan, your rate
limit, and your credit balance.
Each response returns a request ID in X-Enigma-Request-Id. To set your own ID,
send it in the Enigma-Request-Id header.
2. Validate
Section titled “2. Validate”The API parses the query and checks it against the schema. A query that fails
gets a 400 response with errors and no data.
A search with a prompt is rewritten at this stage. The API writes a search
query from the prompt and runs it in place of yours, so the search must have
no selection set.
3. Rate limit
Section titled “3. Rate limit”Only requests that hold a search count against the limit, per API key. The
check runs after validation, so a rejected query does not count.
4. Resolve
Section titled “4. Resolve”- Credits. A
searchchecks your credit balance first. With no credits left, it fails with a 400 response. - Match. The API scores candidate records against your
match fields and keeps those at or above
matchThreshold, up toconditions.limit. A search byidskips scoring. - Connections. The API reads each
connection for all results at once, one
level at a time. Deep queries and large
firstvalues are the usual cause of a 504 response. - Directives. Directives run on the
finished data. They reshape the response but do not reduce the work. A field
with
@skipis still read.
5. Respond
Section titled “5. Respond”- A 400 response can hold
dataanderrorstogether, when some fields fail. - A response over about 6 MB returns a 302 to a file URL that is valid for 24 hours.
X-Enigma-Data-Asset-Versionnames the data release that answered the request.
Background tasks
Section titled “Background tasks”Some requests answer before the work is done:
| Request | Status |
|---|---|
search with output |
202 |
enrich |
202 |
| Values that take more than a few seconds to compute | 206, with the data that is ready |
The task is under extensions.backgroundTasks. Poll
backgroundTask with its id.
There are no webhooks. Only the API key that started a task can read it.
6. Usage
Section titled “6. Usage”The API records usage after the response. A background task records usage when its work is done. Usage depends on the fields that you select, not only on the number of requests.