Ingestion Status

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

const status = await client.context.status({
  database: "acme_corp",
  collection: "team_docs",
  ids: ["policy_main", "runbook_deploy"],
});

curl -G 'https://api.hydradb.com/context/status' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "collection=team_docs" \
  --data-urlencode "ids=policy_main,runbook_deploy"

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

{
  "success": false,
  "data": null,
  "error": {
    "code": "DATABASE_NOT_FOUND",
    "message": "Database not found"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

GET

context

status

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

const status = await client.context.status({
  database: "acme_corp",
  collection: "team_docs",
  ids: ["policy_main", "runbook_deploy"],
});

curl -G 'https://api.hydradb.com/context/status' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "collection=team_docs" \
  --data-urlencode "ids=policy_main,runbook_deploy"

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

{
  "success": false,
  "data": null,
  "error": {
    "code": "DATABASE_NOT_FOUND",
    "message": "Database not found"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

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.

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

const status = await client.context.status({
  database: "acme_corp",
  collection: "team_docs",
  ids: ["policy_main", "runbook_deploy"],
});

curl -G 'https://api.hydradb.com/context/status' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "API-Version: 2" \
  --data-urlencode "database=acme_corp" \
  --data-urlencode "collection=team_docs" \
  --data-urlencode "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.
	Collection scope. If omitted, the default collection is used.

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

{
  "success": false,
  "data": null,
  "error": {
    "code": "DATABASE_NOT_FOUND",
    "message": "Database not found"
  },
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 4.8
  }
}

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	Reason for an error. Empty otherwise. See error code values.
`error_message`	string	Explanation of an ingestion failure. Empty otherwise, including for `FILE_NOT_FOUND`.
`message`	string	Lookup message. Use `indexing_status` and `error_code` to check ingestion.

Error code values

error_code explains why an ID was not found or ingestion failed. It is empty unless indexing_status is errored.

`error_code`	Meaning	What to do
`FILE_NOT_FOUND`	The ID was not found in this database and collection.	Check the ID and scope, or ingest the source.
`E####`	Ingestion failed.	Follow the error code guidance.

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. Use error_code in your application logic. Message text may change.

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	Searchable through `/query`. Graph processing is still in progress.
`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.

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 len(statuses) == len(ids) and 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)

const ids = ["policy_main", "runbook_deploy"];

while (true) {
  const response = await client.context.status({
    database: "acme_corp",
    collection: "team_docs",
    ids: ids,
  });

  const statuses = response.data?.statuses?.map((s) => s.indexingStatus) ?? [];
  if (statuses.length === ids.length && statuses.every((s) => s === "graph_creation" || s === "completed")) break;
  if (statuses.some((s) => s === "errored")) throw new Error("Context processing failed");

  await new Promise((r) => setTimeout(r, 5000));
}

Stop when graph processing is complete

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

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 len(statuses) == len(ids) and 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.

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

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer <your_api_key>.

Query Parameters

string

One context ID. Combined with ids.

Example:

"HydraDoc1234"

ids

string[]

Context IDs as repeated params (ids=a&ids=b) or one comma-joined value (ids=a,b). Whitespace is trimmed; empty and duplicate entries are dropped.

Example:

["HydraDoc1234", "HydraDoc4567"]

database

string

required

Database the contexts belong to. Required.

Example:

"acme_corp"

collection

string

Collection the contexts belong to. Omit it to use the database's default collection.

Example:

"team_docs"

tenant_id

string

deprecated

Deprecated: use database.

Example:

"tenant_1234"

sub_tenant_id

string

deprecated

Deprecated: use collection.

Example:

"sub_tenant_4567"

Response

data

IngestionV2BatchProcessingStatus · object

Show child attributes

Example:

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

error

HandlerApiError · object | null

Error details on failure, or null on success.

Show child attributes

Example:

null

API Documentation

Databases

Context

Query

Connectors

Webhooks

Miscellaneous

Query parameters

Status item fields

Error code values

Status values

Polling patterns

Stop when content is searchable

Stop when graph processing is complete

Errors

Authorizations

Query Parameters

Response

​Query parameters

​Status item fields

​Error code values

​Status values

​Polling patterns

​Stop when content is searchable

​Stop when graph processing is complete

​Errors

​Related resources

Authorizations

Query Parameters

Response

Query parameters

Status item fields

Error code values

Status values

Polling patterns

Stop when content is searchable

Stop when graph processing is complete

Errors

Related resources