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": "",
"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": "ID not found",
"success": false,
"message": "Processing status retrieved successfully"
}
]
},
"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
}
}
Context
Ingestion Status
Check the processing status of ingested documents.
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": "",
"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": "ID not found",
"success": false,
"message": "Processing status retrieved successfully"
}
]
},
"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 one or more IDs in
The normal progression is
Typical processing time:
ids to retrieve status. Works for documents, app sources, and memories. When passing multiple IDs on the query string, use either repeated params (?ids=policy_main&ids=runbook_deploy) or a single comma-joined value (?ids=policy_main,runbook_deploy); both forms are equivalent and can be mixed. Surrounding whitespace is trimmed and empty entries are dropped. For more information, see the Knowledge and Memories guides.
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. | |
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": 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": "ID not found",
"success": false,
"message": "Processing status retrieved successfully"
}
]
},
"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 indata.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 non-empty error_code; empty otherwise. |
success | boolean | false when indexing_status is errored, otherwise true. Describes the item, not the HTTP request - a 200 response can contain errored items. |
message | string | Status of the lookup itself (“Processing status retrieved successfully”). 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 or an id that was never ingested (or whose status has expired). | Fix the id, or (re-)ingest the source. Not a processing failure - retrying the status call will not change it. |
INVALID_FILE_ID | The id was empty or blank. | Send a non-empty id. |
| ingestion-pipeline codes | A genuine processing failure (e.g. PARSE_FAILED, UNSUPPORTED_FORMAT, PROCESSING_FAILED, 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). |
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. |
queued → processing → graph_creation → 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 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.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.
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)
- Memories (text, markdown, conversation pairs): seconds
- Small documents (under 50 pages): 1–5 minutes
- Large documents (50+ pages): 5–15 minutes
Behavior notes
graph_creation is searchable. Items in this state are already retrievable via /query. Wait for completed only when you specifically need full graph traversal (graph_context: true).- Unknown IDs return as
errored: If you pass an ID that does not exist (e.g., a typo), HydraDB returns an entry withindexing_status: "errored"anderror_code: "FILE_NOT_FOUND"rather than silently dropping it. Useerror_codeto distinguish this from a genuine ingestion failure - seeerror_codevalues.
Errors
Common codes:400 INVALID_PARAMETERS, 404 DATABASE_NOT_FOUND, 422 VALIDATION_ERROR. 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
API key sent as a Bearer token: "Bearer prefix.secret"
Query Parameters
Single source ID
Example:
"HydraDoc1234"
One or more source IDs
Example:
["HydraDoc1234", "HydraDoc4567"]
Database (canonical name for the tenant scope)
Example:
"acme_corp"
Collection (canonical name for the sub-tenant scope)
Example:
"team_docs"
Deprecated alias for database
Example:
"tenant_1234"
Deprecated alias for collection
Example:
"sub_tenant_4567"
Response
OK
Show child attributes
Show child attributes
Example:
{
"statuses": [
{
"error_code": "",
"error_message": "",
"id": "HydraDoc1234",
"indexing_status": "completed",
"message": "Source processed successfully.",
"success": true
}
]
}
Error message, empty string on success.
Show child attributes
Show child attributes
Example:
{
"code": "DATABASE_NOT_FOUND",
"message": "Database not found"
}
Show child attributes
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": "sub_tenant_4567",
"tenant_id": "tenant_1234"
}
Whether the request succeeded.
Example:
true
Was this page helpful?