---
title: niyra_get_task — poll long-running tasks
description: Check status, intermediate output, and final result for tasks spawned by niyra_execute or niyra_ask under the spawn-on-timeout pattern.
url: /docs/api-tool-niyra-get-task
lastUpdated: 2026-06-11
---

# niyra_get_task — poll long-running tasks


# 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

```json
{
  "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

```python
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

- [niyra_execute](/docs/api-tool-niyra-execute) — the tool that spawns tasks
- [niyra_ask](/docs/api-tool-niyra-ask) — also spawns under timeout
- [Rate limits](/docs/api-rate-limits)