---
title: "ai.batch-item@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/ai.batch-item"
updated: null
---

# ai.batch-item@1 · OpenVibe.Services

HTML: [ai.batch-item@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/ai.batch-item)

# AiBatchItem `ai.batch-item@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

- Version: 1.0.0
- Owner: ai
- Visibility: first-party
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/ai/batch-item.v1.json`](/docs/contracts/ai.batch-item.json)

ai.batch-item@1: one prompt of a batch on OpenVibe.AI (POST /api/v1/batches). The item is the queue and the status of that one prompt: it waits for capacity (or for a provider's own batch API), runs, and carries the answer, the run it made and the money. A prompt that reached its deadline without capacity expires and is never charged.

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `idx` | integer | yes | The item's place in the batch. | - `minimum 0` |
| `status` | enum | yes | queued (asked for, not started), waiting (no cheap capacity yet), running (a provider works on it), succeeded, failed, expired (the deadline passed; not charged), cancelled (the batch was cancelled). | - `one of "queued", "waiting", "running", "succeeded", "failed", "expired", "cancelled"` |
| `model` | string \| null | yes | The model the item asked for, or the batch's own. |  |
| `run_id` | string \| null | yes | The run the item made, when it made one. | - `pattern ^run_[0-9A-HJKMNP-TV-Z]{26}$` |
| `answer` | string \| null | yes | The answer the provider gave, as text. |  |
| `error_code` | string \| null | yes |  |  |
| `error_detail` | string \| null | yes |  |  |
| `reason` | string \| null | yes | The plain note about the prompt: it expired (it was not charged), it was cancelled before it ran (it was not charged), or it was already sent to the provider (it finishes and is charged). |  |
| `capacity` | string \| null | yes | Where the answer came from: a community offer, the regular capacity, or a provider's own batch API. |  |
| `route_provider` | string \| null | yes |  |  |
| `route_model` | string \| null | yes |  |  |
| `cost_nano_usd` | string \| null |  | What the answer really cost, in nano-USD (1 USD = 1e9 nano), as a string: the money is never a float. |  |
| `absorbed_nano_usd` | string \| null |  | What the network absorbed (the route cost more than the customer paid), in nano-USD, as a string. |  |
| `charged_nano_usd` | string \| null |  | What the customer was charged, in nano-USD, as a string: half the retail card. |  |
| `deadline_at` | string | yes |  | - `format date-time` |
| `created_at` | string | yes |  | - `format date-time` |
| `updated_at` | string | yes |  | - `format date-time` |

## Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

 Valid: one-item

~~~~
{
  "idx": 0,
  "status": "succeeded",
  "model": "gpt-4o-mini",
  "run_id": "run_01K6R3A1B2C3D4E5F6G7H8J9KF",
  "answer": "A digest of the week.",
  "error_code": null,
  "error_detail": null,
  "reason": null,
  "capacity": "regular",
  "route_provider": "openai",
  "route_model": "gpt-4o-mini",
  "cost_nano_usd": "1200",
  "absorbed_nano_usd": "0",
  "charged_nano_usd": "600",
  "deadline_at": "2026-11-08T22:58:00.000Z",
  "created_at": "2026-11-07T22:58:00.000Z",
  "updated_at": "2026-11-08T00:10:00.000Z"
}
~~~~

Rejected: no-idx

~~~~
{
  "status": "succeeded",
  "model": "gpt-4o-mini",
  "run_id": "run_01K6R3A1B2C3D4E5F6G7H8J9KF",
  "answer": "A digest of the week.",
  "error_code": null,
  "error_detail": null,
  "reason": null,
  "capacity": "regular",
  "route_provider": "openai",
  "route_model": "gpt-4o-mini",
  "cost_nano_usd": "1200",
  "absorbed_nano_usd": "0",
  "charged_nano_usd": "600",
  "deadline_at": "2026-11-08T22:58:00.000Z",
  "created_at": "2026-11-07T22:58:00.000Z",
  "updated_at": "2026-11-08T00:10:00.000Z"
}
~~~~

Rejected: unknown-status

~~~~
{
  "idx": 0,
  "status": "later",
  "model": "gpt-4o-mini",
  "run_id": "run_01K6R3A1B2C3D4E5F6G7H8J9KF",
  "answer": "A digest of the week.",
  "error_code": null,
  "error_detail": null,
  "reason": null,
  "capacity": "regular",
  "route_provider": "openai",
  "route_model": "gpt-4o-mini",
  "cost_nano_usd": "1200",
  "absorbed_nano_usd": "0",
  "charged_nano_usd": "600",
  "deadline_at": "2026-11-08T22:58:00.000Z",
  "created_at": "2026-11-07T22:58:00.000Z",
  "updated_at": "2026-11-08T00:10:00.000Z"
}
~~~~

## Validate

~~~~
const contracts = require('openvibe-contracts');
contracts.validate('ai.batch-item@1', value);   // { valid, errors: [{ path, message }] }
~~~~