Skip to content
Console(opens in a new tab)

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.

  1. 1AuthenticateChecks the API key
    • 401Missing or invalid key
    • 403Disabled key
  2. 2ValidateParses and checks the query
    • 400Invalid query
  3. 3Rate limitSearches only, per key
    • 429Over the limit
  4. 4ResolveCredits, match, connections, directives
    • 400No credits
    • 504Too slow
  5. 5RespondSets the status and headers
    • 200Answer
    • 400Partial answer
    • 202, 206Background task
    • 302Over 6 MB
  6. 6UsageRecorded after the response

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.

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.

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.

  1. Credits. A search checks your credit balance first. With no credits left, it fails with a 400 response.
  2. Match. The API scores candidate records against your match fields and keeps those at or above matchThreshold, up to conditions.limit. A search by id skips scoring.
  3. Connections. The API reads each connection for all results at once, one level at a time. Deep queries and large first values are the usual cause of a 504 response.
  4. Directives. Directives run on the finished data. They reshape the response but do not reduce the work. A field with @skip is still read.
  • A 400 response can hold data and errors together, 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-Version names the data release that answered the request.

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.

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.