Ingestion Status

Check whether ingested documents, app sources, or memories are ready to query.

GET /context/status

Python SDK

status = client.context.status(
    database="acme_corp",
    collection="team_docs",
    ids=["policy_main", "runbook_deploy"],
)

Success

{
  "success": true,
  "data": {
    "statuses": [
      {
        "id": "policy_main",
        "indexing_status": "completed",
        "error_code": "",
        "success": true,
        "message": "Processing status retrieved successfully"
      },
      {
        "id": "runbook_deploy",
        "indexing_status": "graph_creation",
        "error_code": "",
        "success": true,
        "message": "Processing status retrieved successfully"
      },
      {
        "id": "typo_in_id",
        "indexing_status": "errored",
        "error_code": "FILE_NOT_FOUND",
        "error_message": "",
        "success": false,
        "message": "ID not found"
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

Since ingestion is asynchronous, use this endpoint to determine when context is ready to be retrieved.

Pass the IDs you got back from ingestion in ids (or a single id). It works for documents, app sources, and memories. Whitespace is trimmed, empty entries are dropped, and duplicates are removed.

Prefer webhooks over polling? Register a webhook for indexing.status_changed events and HydraDB will POST to your endpoint when content reaches a terminal state (completed or errored). See Webhooks for setup and receiver examples.

Python SDK

status = client.context.status(
    database="acme_corp",
    collection="team_docs",
    ids=["policy_main", "runbook_deploy"],
)

Query parameters

Name	Description
	One or more id values returned at ingestion. Accepts IDs for documents, app sources, or memories. Pass either repeated params (ids=a&ids=b) or a single comma-joined value (ids=a,b). Source IDs never contain commas (they are rejected at ingest), so the comma-joined form always splits unambiguously.
	A single ID. Merged with ids when you send both. At least one ID across id and ids is required.
	Database the items belong to. Formerly tenant_id; the tenant_id alias is still accepted (deprecated).
	Collection scope. If omitted, the default collection is used. Formerly sub_tenant_id; the sub_tenant_id alias is still accepted (deprecated). (default=null)

Success

{
  "success": true,
  "data": {
    "statuses": [
      {
        "id": "policy_main",
        "indexing_status": "completed",
        "error_code": "",
        "success": true,
        "message": "Processing status retrieved successfully"
      },
      {
        "id": "runbook_deploy",
        "indexing_status": "graph_creation",
        "error_code": "",
        "success": true,
        "message": "Processing status retrieved successfully"
      },
      {
        "id": "typo_in_id",
        "indexing_status": "errored",
        "error_code": "FILE_NOT_FOUND",
        "error_message": "",
        "success": false,
        "message": "ID not found"
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

Status item fields

Each entry in data.statuses describes one requested id:

Field	Type	Description
id	string	The source, app-source, or memory ID you asked about (echoed back).
indexing_status	string	One of the status values below. errored is terminal.
error_code	string	Machine-readable reason an entry is errored; empty string ("") when the entry is not errored. See error_code values.
error_message	string	Human-readable explanation that accompanies a pipeline error_code; empty otherwise, including for FILE_NOT_FOUND.
success	boolean	Deprecated. false when indexing_status is errored, otherwise true. Describes the item, not the HTTP request: a 200 response can contain errored items. Read indexing_status instead.
message	string	Status of the lookup itself (“Processing status retrieved successfully”, or “ID not found” for an unknown id). It does not describe the ingestion outcome. Read indexing_status / error_code for that.

Error code values

error_code is the field that lets you tell a caller mistake apart from a real ingestion failure, a distinction you cannot make from indexing_status: "errored" alone. It is empty on any non-errored entry.

error_code	Meaning	What to do
FILE_NOT_FOUND	No source with this id exists in the given database/collection: usually a typo, an id that was never ingested, or a deleted source.	Fix the id, or (re-)ingest the source. Not a processing failure, so retrying the status call will not change it.
ingestion-pipeline codes	A genuine processing failure, as a numeric E#### code (e.g. E1001 parse failed, E2002 no text extracted, E4001 embedding failed).	Act on the specific code. See the Error Responses reference. Many are re-ingest-and-retry; some are terminal (unsupported format, empty content).

Status records can expire. A source that completed still reports completed after its record expires. A source that never finished before its record expired reports errored with E9004; ingest it again.

Branch on error_code, not on the text in message or error_message. message describes the lookup, not the ingestion result, and human-readable text may change. The full list of codes an errored entry can carry is in the Error Responses reference.

Status values

Status	Searchable?	Meaning
queued	No	Accepted by the server, not yet picked up by a worker.
processing	No	Content is being parsed, chunked, and embedded.
graph_creation	Yes	Indexed and retrievable; the knowledge graph is still being built. Already searchable via /query, but graph context may still be incomplete.
completed	Yes	Fully indexed and graphed. Ready for all retrieval modes.
errored	No	Processing failed. Inspect error_code and error_message.

The normal progression is queued, then processing, then graph_creation, then completed. Treat errored as terminal.

Polling patterns

Stop when content is searchable

Use this for normal RAG/search flows. graph_creation means chunks are indexed and can be retrieved.

Python

import time

ids = ["policy_main", "runbook_deploy"]

while True:
    response = client.context.status(
        database="acme_corp",
        collection="team_docs",
        ids=ids,
    )
    statuses = [s.indexing_status for s in response.data.statuses]

    if all(s in ("graph_creation", "completed") for s in statuses):
        break
    if any(s == "errored" for s in statuses):
        raise RuntimeError("Context processing failed")

    time.sleep(5)

Stop when graph processing is complete

Use this before graph-heavy operations such as /context/relations or when you require complete graph_context.

while True:
    response = client.context.status(
        database="acme_corp",
        collection="team_docs",
        ids=["policy_main", "runbook_deploy"],
    )
    statuses = [s.indexing_status for s in response.data.statuses]

    if all(s == "completed" for s in statuses):
        break
    if any(s == "errored" for s in statuses):
        raise RuntimeError("Graph processing failed")

    time.sleep(5)

Typical processing time:

• Memories (text, markdown, conversation pairs): seconds
• Small documents (under 50 pages): 1 to 5 minutes
• Large documents (50+ pages): 5 to 15 minutes

Errors

Common codes: 400 INVALID_INPUT (for example database and tenant_id both sent with different values), 404 DATABASE_NOT_FOUND, 422 VALIDATION_ERROR (missing database, or no ID). See Error Responses for the full list.

Related Resources

• Before this: Ingest Context, to get the IDs
• After completion: Query
• After completion: Fetch Content
• After completion: Context Relations
• Read more: Usage: Knowledge
• Read more: Usage: Memories

Authorizations

Authorization · string · header · required

API key sent as a Bearer token: "Bearer prefix.secret"

Query Parameters

id · string

Single source ID

Example:

"HydraDoc1234"

ids · string[]

One or more source IDs

Example:

["HydraDoc1234", "HydraDoc4567"]

database · string · required

Database (canonical name for the tenant scope)

Example:

"acme_corp"

collection · string

Collection (canonical name for the sub-tenant scope)

Example:

"team_docs"

tenant_id · string · deprecated

Deprecated alias for database

Example:

"tenant_1234"

sub_tenant_id · string · deprecated

Deprecated alias for collection

Example:

"sub_tenant_4567"

Response

200

application/json

OK

data · object

Show child attributes

Example:

{
  "statuses": [
    {
      "error_code": "",
      "error_message": "",
      "id": "HydraDoc1234",
      "indexing_status": "completed",
      "message": "Source processed successfully.",
      "success": true
    }
  ]
}

error · object | null

Null on success; an object with code and message on failure.

Show child attributes

Example:

null

meta · object

Show child attributes

Example:

{
  "collection": "team_docs",
  "database": "acme_corp",
  "latency_ms": 12.3,
  "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
  "source_type": "file",
  "sub_tenant_id": "team_docs",
  "tenant_id": "acme_corp"
}

success · boolean

Whether the request succeeded.

Example:

true