> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create batch > API reference for POST /v3/router/batches. Start a batch from an uploaded JSONL file. > [!NOTE] > > **Related guide**: Batches guide. See the [Batches guide](https://docs.orq.ai/ai-gateway/features/batches.md) for the input file format, supported endpoints, and result files. ## OpenAPI ````yaml post /v3/router/batches openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://my.orq.ai security: - ApiKey: [] tags: - name: Chunking description: Split text into smaller chunks for retrieval and generation workflows. - name: File Systems description: >- Create and manage persistent file systems that agents and MCP clients read from and write to. - name: Knowledge Bases description: Create and manage knowledge bases used by agents and retrieval workflows. - name: Memory Stores description: Create and manage memory stores, memories, and memory documents. - name: Evals description: Run an evaluator against a conversation and its result - name: Logs description: >- OpenTelemetry log query API. Search, filter, aggregate, and facet log records ingested via OTLP. - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: Traces description: >- Query and inspect ingested trace data: search trace summaries, aggregate metrics, and read individual traces and their spans. - description: List models available through the AI Router. name: Models - name: Policies - name: Alerts description: >- Alerts evaluate a Reporting API metric on a fixed interval and fire notifications through notifiers when the value breaches a threshold. Each breach opens a trigger that tracks the incident until the value recovers. - name: Annotation Queues description: Annotation queues collect spans for human review. - name: API keys description: >- API keys authenticate programmatic access to the workspace. They expose opaque tokens, per-domain access grants, and budget and rate-limit constraints. - name: Audit Logs description: Audit logs record workspace entity changes and access-relevant events. - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, API key, provider, and model. Every applicable budget is enforced, and the most restrictive limit applies per dimension. - name: Files description: File upload and retrieval operations. - name: Guardrail Rules description: >- Guardrail Rules conditionally enforce evaluators and plugins for AI Gateway traffic. Rules may be scoped to a project or the whole workspace. - name: Hub description: Hub items are reusable templates available to a workspace. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Management keys description: >- Management keys are workspace-scoped credentials that authenticate programmatic access to workspace administration surfaces (API keys, budgets). Unlike project-scoped API keys, a management key always operates at the workspace level. - name: MCP Gateway description: >- Register upstream MCP servers, discover and sync their tools, and assemble gateways that expose a curated tool surface to MCP clients. - name: Model Catalog description: >- Browse the orq.ai model catalog: every model orq offers, across every provider, with pricing, capabilities and benchmark data. List endpoints only return models that are not deprecated. This API is public, requires no authentication, and is rate limited to 120 requests per minute per IP. Responses carry a 5-minute cache-control max-age. - name: Model Fusions description: >- Model Fusions combine independent model answers through a panel, judge, and optional synthesizer. - name: Monitors description: >- Monitors are custom observability dashboards for traces, runtime metrics, and logs. Each monitor holds widgets that chart one telemetry query. List the metrics, operations, and dimensions available to your workspace with `GET /v3/telemetry/capabilities`, or start from a preset with `GET /v2/monitors/presets`. - name: Notifiers description: Notifier destinations used to send delivery and workflow notifications. - name: Projects description: Projects organize resources within a workspace - name: Routing Rules description: >- Routing Rules conditionally select models and enforce request plugins for AI Gateway traffic. Rules are evaluated by ascending priority and may be scoped to a project or the whole workspace. - name: Threads description: Threads group related trace invocations and their aggregate usage - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Smart Routers description: >- Create and manage workspace Smart Routers. A Smart Router selects a model from an eligible pool for each request according to a quality, balanced, or cost profile. - name: Webhooks description: >- Create and manage webhooks that deliver workspace events to external HTTPS endpoints. - name: Workspaces description: >- A workspace is the tenant. Create is called from a user session during onboarding; Get, List, and Update are the public management surface. - name: Workspace Security description: >- Workspace-level domain verification and IP allowlist controls. These operations are restricted to workspace administrators. - name: Workspace Settings description: >- Workspace-level settings managed with a workspace credential. A workspace is the tenant, so these settings are a singleton — there is nothing to create or delete, only read and update. - name: Responses - description: Run agents on a cron cadence. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - name: Telemetry description: >- Unified query envelope for traces, metrics, and logs. One request shape, one filter dialect, and one response shape per source, validated by a per-source registry. - description: Beta. Run typed classification questions against a classify model. name: Classify - description: Search Gateway with managed credits or BYOK. name: Web Search - description: Beta. Run classification decisions with the classify contract. name: Decisions - name: Users description: >- Workspace user administration. Requires a Management Key with user permissions or an authenticated workspace admin session. Standard API keys are not supported. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v3/router/batches: post: tags: - Batches summary: Create batch description: >- Creates a batch from an uploaded JSONL file whose purpose is `batch`. Each line is sent to `endpoint` with its own request body, without the throughput limits of real-time traffic. Provider batches run through the provider's batch service at its batch rates; `/v3/router/decisions` batches run on **Orq.ai** workers. See the [Batches guide](/ai-gateway/features/batches) for input file format, supported endpoints, and result files. operationId: create-batch requestBody: content: application/json: examples: chat_completions: summary: Batch of chat completions value: completion_window: 24h endpoint: /v1/chat/completions input_file_id: file-abc123 metadata: job: nightly-eval schema: additionalProperties: false properties: completion_window: description: Time window the batch runs in. Only 24h is supported. enum: - 24h type: string endpoint: description: >- Endpoint each line is sent to. The batch model must support it. enum: - /v1/responses - /v1/chat/completions - /v1/embeddings - /v1/completions - /v1/moderations - /v3/router/decisions type: string input_file_id: description: ID of an uploaded JSONL file whose purpose is batch. type: string metadata: additionalProperties: type: string description: >- Up to 16 key/value pairs, keys up to 64 characters and values up to 512. type: object output_expires_after: $ref: '#/components/schemas/PublicBatchExpiresAfter' description: Expiration applied to the output and error files. required: - input_file_id - endpoint - completion_window type: object required: true responses: '200': content: application/json: schema: additionalProperties: false properties: cancelled_at: description: Time the batch finished cancelling, in Unix seconds. format: int64 type: integer cancelling_at: description: Time cancellation was requested, in Unix seconds. format: int64 type: integer completed_at: description: Time the batch completed, in Unix seconds. format: int64 type: integer completion_window: description: Time window the batch runs in, always 24h. type: string created_at: description: Creation time, in Unix seconds. format: int64 type: integer endpoint: description: Endpoint each line of the input file is sent to. type: string error_file_id: description: >- ID of the JSONL file holding per-line errors, when any line failed. type: string errors: $ref: '#/components/schemas/PublicBatchErrors' description: >- Errors that prevented the batch from running, when the status is failed. expired_at: description: Time the batch expired, in Unix seconds. format: int64 type: integer expires_at: description: Time the batch expires, in Unix seconds. format: int64 type: integer failed_at: description: Time the batch failed, in Unix seconds. format: int64 type: integer finalizing_at: description: >- Time the batch began assembling its result files, in Unix seconds. format: int64 type: integer id: description: Batch identifier. type: string in_progress_at: description: Time the batch started running, in Unix seconds. format: int64 type: integer input_file_id: description: ID of the uploaded JSONL input file. type: string metadata: additionalProperties: type: string description: Metadata supplied at creation. type: object model: description: Model resolved for the batch. type: string object: description: Object type, always batch. type: string output_file_id: description: >- ID of the JSONL file holding successful responses, set once the batch completes. type: string request_counts: $ref: '#/components/schemas/PublicBatchRequestCounts' description: Per-line progress counters. status: description: Current batch status. enum: - validating - in_progress - finalizing - completed - failed - expired - cancelling - cancelled type: string usage: $ref: '#/components/schemas/PublicBatchUsage' description: Token usage summed over the successful lines. required: - id - object - endpoint - input_file_id - completion_window - status - created_at - request_counts type: object description: Batch created. Poll or list it until it reaches a terminal status. '400': content: application/json: schema: type: object additionalProperties: false properties: error: $ref: '#/components/schemas/APIError' required: - error description: >- Invalid body, unsupported endpoint, completion window other than 24h, or an input file that is missing the batch purpose. '401': content: application/json: schema: type: object additionalProperties: false properties: error: $ref: '#/components/schemas/APIError' required: - error description: Missing, invalid, expired or revoked API key. '404': content: application/json: schema: type: object additionalProperties: false properties: error: $ref: '#/components/schemas/APIError' required: - error description: The input file does not exist in the caller's projects. '500': content: application/json: schema: type: object additionalProperties: false properties: error: $ref: '#/components/schemas/APIError' required: - error description: An internal error occurred. x-code-samples: - label: Node.js lang: typescript source: |- const batch = await orq.batches.create({ inputFileId: "file-abc123", endpoint: "/v1/chat/completions", completionWindow: "24h", }); components: schemas: PublicBatchExpiresAfter: additionalProperties: false properties: anchor: description: Point the lifetime starts from. Defaults to created_at. enum: - created_at type: string seconds: description: Lifetime of the file, in seconds. format: int64 type: integer required: - seconds type: object PublicBatchErrors: additionalProperties: false properties: data: description: Errors that stopped the batch. items: $ref: '#/components/schemas/PublicBatchError' type: - array - 'null' object: description: Object type, always list. type: string required: - object - data type: object PublicBatchRequestCounts: additionalProperties: false properties: completed: description: Lines that completed successfully. format: int64 type: integer failed: description: Lines that failed. format: int64 type: integer total: description: Lines in the input file. format: int64 type: integer required: - total - completed - failed type: object PublicBatchUsage: additionalProperties: false properties: input_tokens: description: Input tokens over the successful lines. format: int64 type: integer input_tokens_details: $ref: '#/components/schemas/PublicBatchUsageInputTokenDetails' output_tokens: description: Output tokens over the successful lines. format: int64 type: integer output_tokens_details: $ref: '#/components/schemas/PublicBatchUsageOutputTokenDetails' total_tokens: description: Input and output tokens combined. format: int64 type: integer required: - input_tokens - input_tokens_details - output_tokens - output_tokens_details - total_tokens type: object APIError: additionalProperties: false properties: code: type: - string - 'null' failures: {} message: type: string param: type: - string - 'null' type: type: string required: - message - type - param - code type: object PublicBatchError: additionalProperties: false properties: code: description: Machine-readable error code. type: string line: description: Input file line the error refers to, when it is line-specific. format: int64 type: integer message: description: Human-readable error message. type: string param: description: Request field the error refers to, when it is field-specific. type: string required: - code - message type: object PublicBatchUsageInputTokenDetails: additionalProperties: false properties: cached_tokens: description: Input tokens served from the provider cache. format: int64 type: integer required: - cached_tokens type: object PublicBatchUsageOutputTokenDetails: additionalProperties: false properties: reasoning_tokens: description: Output tokens spent on reasoning. format: int64 type: integer required: - reasoning_tokens type: object securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.