---
title: "Enqueue an async document agent job"
method: POST
path: "/document/agent/jobs"
tags: ["Usage"]
---

# Enqueue an async document agent job

`POST /document/agent/jobs`

Create a long-running document agent job. Returns immediately with a `job_id` — use GET /document/agent/jobs/{job_id} to poll for the result or GET /document/agent/jobs/{job_id}/stream for live SSE updates.

Recommended for production workloads, batch evaluation pipelines, or anything that may run longer than ~10 minutes. The job runs on a background worker pool with 30-minute hard timeout, per-user concurrency caps, and automatic refunds on failure.

## Request body

- DocumentQueryRequest — Request for the v2 document/agent endpoint.
  - `source_id` string, nullable — Data source ID of a single indexed document
  - `source_ids` string[], nullable — List of data source IDs for multi-document queries (max 50)
  - `query` string, required — Question to ask about the document(s)
  - `json_schema` object, nullable — JSON Schema for structured output
  - `model` string — Model to use (claude-opus-4-7, claude-sonnet-4-5-20250929, etc.)
  - `thinking_enabled` boolean — Enable extended thinking
  - `thinking_budget` integer — Token budget for thinking (ignored for adaptive models like Opus 4.7)
  - `stream` boolean — Stream response as SSE events

## Response `200`

Successful Response

- DocumentAgentJobResponse — Returned by POST /document/agent/jobs.
  - `job_id` string, required — Workflow run id — pass to GET/stream/cancel endpoints
  - `status` string, required — Initial status — usually 'queued'
  - `created_at` string, required
  - `message` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/trynia/apis/nia-ai-api.md) · [All operations](https://skmtc.net/trynia/apis/nia-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trynia/nia-ai-api/versions/d216ffc3efb6/schema)