Check status, intermediate output, and final result for tasks spawned by niyra_execute or niyra_ask under the spawn-on-timeout pattern.
niyra_get_task
When a niyra_execute or niyra_ask call exceeds its synchronous window, the response includes a task_id and the work continues in the background. This endpoint is how you check on it.
Endpoint
| Method | Path | Auth | Scope |
|---|
| GET | /v1/public/tasks/{task_id} | Bearer token | niyra:tasks:read |
MCP equivalent: POST /mcp with method tools/call, name niyra_get_task, args {"task_id": "..."}.
Response
{
"task_id": "task_abc",
"status": "running",
"terminal": false,
"started_at": "2026-06-11T20:00:00Z",
"completed_at": null,
"tools_used": ["web_search", "summarize"],
"result": null,
"partial_text": "Found 12 funding rounds matching your criteria. Drafting summary…",
"error": null
}
| Field | Type | Notes |
|---|
status | enum | pending, running, complete, failed, cancelled |
terminal | bool | True iff status is one of complete / failed / cancelled. Stop polling. |
partial_text | string | Best-effort intermediate output. May lag behind actual progress. Null for failed/cancelled. |
result | string | Final output. Present when status is complete. |
error | object | Present when status is failed. Has code + message. |
Polling pattern
import os, time, requests
def wait_for_task(task_id, token, timeout=600, interval=3):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"https://api.niyra.ai/v1/public/tasks/{task_id}",
headers={"Authorization": f"Bearer {token}"},
)
data = r.json()
if data["terminal"]:
if data["status"] == "complete":
return data["result"]
raise RuntimeError(f"task {data['status']}: {data.get('error')}")
time.sleep(interval)
raise TimeoutError("polled past timeout")
Errors
| Status | Code | Meaning |
|---|
| 401 | invalid_token | Token revoked/expired/unknown |
| 403 | insufficient_scope | Token lacks niyra:tasks:read |
| 404 | not_found | Task ID unknown or owned by a different user |
| 429 | rate_limit_exceeded | You're polling too fast |
Related