---
title: "Create a batch embedding job"
method: POST
path: "/v1/batch/embeddings"
tags: ["Batch Embeddings"]
---

# Create a batch embedding job

`POST /v1/batch/embeddings`

## Request

- Base URL: `https://api.jina.ai`
- URL: `https://api.jina.ai/v1/batch/embeddings`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/jina/apis/jina-search-foundation-api/docs/v1/batch/embeddings/post.ts> (a function with typed inputs; its response is checked against the schema)

Submit a batch of texts for asynchronous embedding processing.

## Request body

- BatchEmbeddingRequest: Request to create a batch embedding job.
  - `model` 'jina-embeddings-v5-text-nano' | 'jina-embeddings-v5-text-small', required: The embedding model to use for batch processing.
  - `input_url` string, nullable: URL to input JSONL file (GCS, S3, or HTTP). Either input_url or input must be provided.
  - `input` object[], nullable: Inline JSONL lines for small batches. Either input_url or input must be provided.
  - `task` string, nullable: Task optimization: retrieval, text-matching, clustering, or classification.
  - `dimensions` integer, nullable: Number of dimensions for output embeddings (1-1024).
  - `normalized` boolean, nullable: If true (default), embeddings are L2-normalized to unit length.
  - `webhook_url` string, nullable: URL to POST notification when job completes.

## Response `200`

Successful Response

- BatchStatus: Status of a batch embedding job.
  - `batch_id` string, required: Unique identifier for the batch job.
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'expired' | 'cancelled', required: Current status of the batch job.
  - `model` string, required: The model used for embedding.
  - `created_at` string, required: ISO 8601 timestamp when job was created.
  - `completed_at` string, nullable: ISO 8601 timestamp when job completed (if finished).
  - `expires_at` string, nullable: ISO 8601 timestamp when output URL expires (created_at + 24h).
  - `output_url` string, nullable: Signed URL to download output JSONL (24h expiry).
  - `error_file_url` string, nullable: URL to download error JSONL for failed lines.
  - `error` string, nullable: Error message if job failed.
  - `stats` BatchStats: Statistics for a batch job.
    - `total` integer, required: Total number of input lines.
    - `completed` integer: Number of successfully processed lines.
    - `failed` integer: Number of failed lines.
    - `total_tokens` integer: Total tokens consumed across all processed lines.

## Other responses

- `400`: Bad Request: `INPUT_INVALID_LABELS`, `INPUT_LABEL_LIMIT_EXCEEDED`, `INPUT_MODEL_NOT_FOUND`, `INPUT_TOKEN_LIMIT_EXCEEDED`
- `401`: Unauthorized: `AUTH_INVALID_API_KEY`, `AUTH_INVALID_FORMAT`, `AUTH_MISSING_API_KEY`
- `403`: Forbidden: `AUTHZ_INSUFFICIENT_BALANCE`, `AUTHZ_RESOURCE_LIMIT_EXCEEDED`
- `404`: Not Found: `RESOURCE_NOT_FOUND`
- `409`: Conflict: `CONFLICT_RESOURCE_BUSY`
- `422`: The request body failed schema validation. `errors` names each field.
- `429`: Too Many Requests: `RATE_CONCURRENCY_LIMIT_EXCEEDED`, `RATE_IP_LIMIT_EXCEEDED`, `RATE_REQUEST_LIMIT_EXCEEDED`, `RATE_TOKEN_LIMIT_EXCEEDED`
- `500`: Internal Server Error: `INTERNAL_ERROR`
- `503`: Service Unavailable: `SERVICE_UNAVAILABLE`
- `504`: Gateway Timeout: `SERVICE_TIMEOUT`

## Changes

- **2026-10-10** `e1c9fccc2a1a`: 19 breaking, 12 info
  - response property `code` list-of-types was widened by adding types `null` to media type `application/json` of response `400`
  - response property `code` list-of-types was widened by adding types `null` to media type `application/json` of response `401`
  - response property `code` list-of-types was widened by adding types `null` to media type `application/json` of response `403`
  - response property `code` list-of-types was widened by adding types `null` to media type `application/json` of response `404`
  - …27 more
- **2026-04-14** `a92cc1f233eb`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/jina/apis/jina-search-foundation-api/changes/v1/batch/embeddings/post.md)

---

[API](https://skmtc.dev/jina/apis/jina-search-foundation-api.md) - [All operations](https://skmtc.dev/jina/apis/jina-search-foundation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jina/apis/jina-search-foundation-api/revisions/e1c9fccc2a1a?raw)