> ## Documentation Index > Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get task predictions > Returns the agent's extraction predictions with visual coordinates for each extracted value. Includes both predicted values and human-reviewed corrections. Coordinates are in the document's native units (PDF points, 72 per inch) by default, or scaled to pixels if a DPI is specified. Each box represents either a field extraction or a table cell location on a specific page. Unlocated fields are returned with coordinates (0,0,0,0). Review edits carry a score of 0. ## OpenAPI ````yaml GET /api/v1/tasks/{task_id}/predictions openapi: 3.1.0 info: title: Nanonets Agents Platform — Public API version: 1.0.0 summary: >- Programmatically run AI agents, send follow-up messages, fetch results, and update agent prompts. description: > The Nanonets Agents Platform Public API lets you trigger agents, stream task progress, and integrate agent outputs into your own systems. ## Authentication All requests must include a workspace API key as a Bearer token: ``` Authorization: Bearer YOUR_API_KEY ``` Workspace API keys are minted from the web app under **Settings → API Keys**. Each key is scoped to a single workspace; requests against agents or tasks outside that workspace return `403`. ## Lifecycle A typical integration is three calls: 1. `POST /v1/agents/{agent_id}/run` — start a task. Returns a `task_id` immediately. 2. Poll `GET /v1/tasks/{task_id}` until `status` is a terminal value (`completed`, `failed`, or `stopped`), **or** wait until it reaches `waiting_for_input` to respond with `POST /v1/tasks/{task_id}/message`. 3. `GET /v1/tasks/{task_id}/summary` for the final answer, or `/result` for the full reasoning trace. ## Errors Every error response is `{"error": ""}`. The HTTP status indicates the class: | Status | Meaning | |--------|---------| | 400 | Malformed request (bad UUID, missing required field, file too large) | | 401 | Missing or invalid API key | | 403 | API key is valid but the agent/task belongs to a different workspace | | 404 | Agent or task not found | | 500 | Server error — safe to retry with backoff | contact: name: Nanonets Support url: https://nanonets.com/support license: name: Proprietary servers: - url: https://agents.nanonets.com description: Production security: - bearerAuth: [] tags: - name: Agents description: Manage agents — create, list, update, run, and version. - name: Tasks description: >- Inspect task status, fetch results, list and cancel tasks, and send follow-up messages. paths: /api/v1/tasks/{task_id}/predictions: get: tags: - Tasks summary: Get extracted predictions with box coordinates description: > Returns the agent's extraction predictions with visual coordinates for each extracted value. Includes both predicted values and human-reviewed corrections. Coordinates are in the document's native units (PDF points, 72 per inch) by default, or scaled to pixels if a DPI is specified. Each box represents either a field extraction or a table cell location on a specific page. Unlocated fields are returned with coordinates (0,0,0,0). Review edits carry a score of 0. operationId: getTaskPredictions parameters: - $ref: '#/components/parameters/TaskIdPath' - name: dpi in: query description: > Optional DPI for coordinate scaling. If omitted, all coordinates and page sizes are in native units. If given (36..1200), coordinates and sizes are multiplied by dpi/72 and rounded to pixels. schema: type: integer minimum: 36 maximum: 1200 responses: '200': description: Task with predictions and box coordinates. content: application/json: schema: $ref: '#/components/schemas/GetTaskPredictionsResponse' '400': description: Bad task ID or DPI out of range. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: >- Task state is not configured for the task's agent (no output schema, or not opted in). content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '501': description: Task state is turned off on this deployment. Not retryable. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: TaskIdPath: name: task_id in: path required: true description: UUID of the task. schema: type: string format: uuid schemas: GetTaskPredictionsResponse: type: object required: - task_id - agent_id - status - moderated_images_count - unmoderated_images_count - moderated_images - unmoderated_images - signed_urls properties: task_id: type: string format: uuid agent_id: type: string format: uuid status: $ref: '#/components/schemas/TaskStatus' moderated_images_count: type: integer description: Count of pages with human review edits. unmoderated_images_count: type: integer description: Count of pages without human review edits. moderated_images: type: array description: Pages that have been human-reviewed (edits applied). items: $ref: '#/components/schemas/PredictionsImage' unmoderated_images: type: array description: Pages awaiting human review. items: $ref: '#/components/schemas/PredictionsImage' signed_urls: type: object description: Map of original file names to signed download URLs. additionalProperties: type: string Error: type: object required: - error properties: error: type: string description: Human-readable error message. examples: - Invalid agent_id format TaskStatus: type: string description: > Lifecycle status of a task. - `pending` — created, not yet picked up - `queued` — held back by admission control (agent at concurrent-task limit) - `running` — being processed by the worker - `waiting_for_input` — agent called `ask_user`; reply with `POST /tasks/{id}/message` - `awaiting_review` — agent is paused for human approval of a sensitive step - `completed` — terminal: finished successfully - `failed` — terminal: errored out - `stopped` — terminal: cancelled by a user or system enum: - pending - queued - running - waiting_for_input - awaiting_review - completed - failed - stopped PredictionsImage: type: object required: - page - size - rotation - url - file_url - status - original_file_name - request_file_id - is_moderated - request_metadata - predicted_boxes - moderated_boxes properties: page: type: integer description: Zero-based page number in the document. size: $ref: '#/components/schemas/PredictionsSize' rotation: type: integer description: Page rotation in degrees (0, 90, 180, or 270). url: type: string description: Signed URL to the rendered page image. file_url: type: string description: Same as url. status: type: string enum: - success - error description: Processing status of this page. original_file_name: type: string description: Original uploaded file name. request_file_id: type: string format: uuid description: Task ID that uploaded the file. is_moderated: type: boolean description: True if this page has human review edits. request_metadata: type: string description: Arbitrary JSON string from the run's metadata. predicted_boxes: type: array description: Agent-extracted values for this page. items: $ref: '#/components/schemas/PredictionsBox' moderated_boxes: type: array description: >- Values after human review edits (identical to predicted_boxes if unreviewed). items: $ref: '#/components/schemas/PredictionsBox' PredictionsSize: type: object required: - width - height - normalized_width - normalized_height properties: width: type: integer description: Page width in scaled units. height: type: integer description: Page height in scaled units. normalized_width: type: integer description: Same as width (repeats the pixel pair). normalized_height: type: integer description: Same as height (repeats the pixel pair). PredictionsBox: type: object required: - id - label - label_id - xmin - ymin - xmax - ymax - score - ocr_text - status - type - page - is_edited - lookup_edited - lookup_parent_box_ids properties: id: type: string format: uuid description: Unique box identifier. label: type: string description: Field or column name. label_id: type: string format: uuid description: Reference to the label definition. xmin: type: integer description: Minimum x coordinate in scaled units. ymin: type: integer description: Minimum y coordinate in scaled units. xmax: type: integer description: Maximum x coordinate in scaled units. ymax: type: integer description: Maximum y coordinate in scaled units. score: type: number format: float minimum: 0 maximum: 1 description: Extraction confidence (0..1). Edited values carry score 0. ocr_text: type: string description: Extracted or edited text value. status: type: string description: >- Extraction status (e.g. "correctly_predicted", "moderated", "success"). type: type: string enum: - field - table description: Box type — field or table region. page: type: integer description: Zero-based page number. is_edited: type: boolean description: True if a human edited this value. lookup_edited: type: boolean description: True if a lookup step edited this value. lookup_parent_box_ids: description: Parent box IDs if this value came from a lookup step. oneOf: - type: 'null' - type: array items: type: string format: uuid validation_status: type: string description: Validation rule status (e.g. "failed"). validation_message: type: string description: Validation error message. cells: type: array description: Table cells within this box. items: $ref: '#/components/schemas/PredictionsCell' PredictionsCell: type: object required: - id - row - col - row_span - col_span - label - xmin - ymin - xmax - ymax - score - text - row_label - status - verification_status - failed_validation - label_id - lookup_edited - is_edited properties: id: type: string format: uuid description: Unique cell identifier. row: type: integer description: One-based row number within the table. col: type: integer description: One-based column number within the table. row_span: type: integer description: Number of rows this cell spans. col_span: type: integer description: Number of columns this cell spans. label: type: string description: Column name or label. xmin: type: integer description: Minimum x coordinate in scaled units. ymin: type: integer description: Minimum y coordinate in scaled units. xmax: type: integer description: Maximum x coordinate in scaled units. ymax: type: integer description: Maximum y coordinate in scaled units. score: type: number format: float minimum: 0 maximum: 1 description: Extraction confidence (0..1). Edited values carry score 0. text: type: string description: Cell value. row_label: type: string description: Row header label if applicable. status: type: string description: Cell status (e.g. "success"). verification_status: type: string description: Human review status (e.g. "moderated"). failed_validation: type: boolean description: True if cell validation failed. label_id: type: string format: uuid description: Reference to the column label definition. lookup_edited: type: boolean description: True if a lookup step edited this value. is_edited: type: boolean description: True if a human edited this value. responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Agent or task not found. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: | Rate limit exceeded for this API key. Rate limiting is enabled per environment, and where it is on the bucket is per key across the whole /v1 surface rather than per route — so polling draws on the same budget as runs. Wait the interval in Retry-After before retrying. headers: Retry-After: schema: type: integer description: Seconds to wait. Never 0. ServerError: description: Unexpected server error. Safe to retry with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: | Workspace API key issued from the web app. Pass as `Authorization: Bearer YOUR_API_KEY`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.