curl --request GET \
--url https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response \
--header 'Authorization: Bearer <token>'import requests
url = "https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"task_id": "f1c2a3b4-0000-0000-0000-000000000000",
"agent_id": "9a8b7c6d-0000-0000-0000-000000000000",
"status": "completed",
"created_at": "2026-09-22T10:00:00Z",
"updated_at": "2026-09-22T10:00:42Z",
"structured_response": {
"invoice_number": "INV-1043",
"total": 1290.5
}
}Get structured output
Returns the JSON object the run produced against its output schema — the
payload shaped by the agent’s configured output keys, or by the
output_config sent with POST /v1/agents/{agent_id}/run.
This is the endpoint to poll when you want machine-readable fields.
/summary returns the agent’s final written answer; /result returns the
whole reasoning transcript. Neither is the schema’d object.
Short of an infrastructure failure, the call answers 200 while the task
exists and belongs to your workspace — a run that produced nothing is not an
error here. Which field is populated says what happened:
| Field | Meaning |
|---|---|
structured_response | The output, present and readable. |
message | The run has not finished (pending, queued, running, waiting_for_input, awaiting_review). Poll again. |
error | No output schema is configured on the agent or the task, or the run ended without writing one. |
curl --request GET \
--url https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response \
--header 'Authorization: Bearer <token>'import requests
url = "https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://agents.nanonets.com/api/v1/tasks/{task_id}/structured-response")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"task_id": "f1c2a3b4-0000-0000-0000-000000000000",
"agent_id": "9a8b7c6d-0000-0000-0000-000000000000",
"status": "completed",
"created_at": "2026-09-22T10:00:00Z",
"updated_at": "2026-09-22T10:00:42Z",
"structured_response": {
"invoice_number": "INV-1043",
"total": 1290.5
}
}Authorizations
Workspace API key issued from the web app. Pass as
Authorization: Bearer YOUR_API_KEY.
Path Parameters
UUID of the task.
Query Parameters
true returns each value with the place in the source document it was read
from, plus a documents block resolving those files.
Two separate switches, deliberately: Keep citations
(structured_output_citations) on the agent decides whether citations are
produced; this parameter decides whether they are returned. So turning
the agent setting on for the dashboard never changes the bytes an existing
API consumer already parses.
Off (the default), every leaf is a plain value, whether or not the agent
keeps citations. On, a leaf that has provenance becomes
{"value": ..., "bounding_boxes": [...]}; leaves with no document source
(a value from a database lookup, say) stay plain. Asking an agent that
keeps no citations is not an error — the payload comes back unchanged and
documents is omitted.
Prefer normalized_bounding_box (0–1, origin top-left) when drawing:
bounding_box is absolute pixels and needs the page dimensions from
documents. Spreadsheet and text sources carry sheet/cell or
line_start/line_end instead of a box.
Response
Task metadata plus the structured output, when one is available.
Lifecycle status of a task.
pending— created, not yet picked upqueued— held back by admission control (agent at concurrent-task limit)running— being processed by the workerwaiting_for_input— agent calledask_user; reply withPOST /tasks/{id}/messageawaiting_review— agent is paused for human approval of a sensitive stepcompleted— terminal: finished successfullyfailed— terminal: errored outstopped— terminal: cancelled by a user or system
pending, queued, running, waiting_for_input, awaiting_review, completed, failed, stopped The run's output against its schema. Leaves are plain values unless
include_citations=true, in which case a leaf with provenance becomes
{ "value": ..., "bounding_boxes": [...] }.
Key filtering rides along with citations rather than being universal:
include_citations=true also drops the platform's internal keys
(__-prefixed, plus _meta on a cited leaf). The default path unwraps
leaves and filters nothing, so an internal key a run happened to write
reaches you unchanged. Read the keys your schema declares rather than
assuming the object holds only those.
Omitted when no output is available — read message / error to tell
"not yet" from "never".
The source files this response's citations name, so a value can be drawn
on the page it came from. Present only with include_citations=true on a
run that produced citations.
Show child attributes
Show child attributes
Set when the run is still in flight, so the output may yet appear. Poll again.
Set when no output can ever arrive for this task — no output schema is configured, or the run reached a terminal state without writing one.