---
title: Пакетная обработка
url: https://platform.claude.com/docs/ru/build-with-claude/batch-processing
description: Асинхронно обрабатывайте большие объёмы запросов Messages с помощью Message Batches API, сокращая затраты на 50 процентов и увеличивая пропускную способность.
featureMetadata:
  status: stable
  zdr:
    eligibility: not-eligible
    note: Хранение 29 дней; требуется асинхронное хранилище.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: stable
    Claude Platform on AWS: stable
    Claude Models on Google Cloud (Anthropic managed): stable
---

Пакетная обработка — это мощный подход к эффективной обработке больших объёмов запросов. Вместо того чтобы обрабатывать запросы по одному с немедленными ответами, пакетная обработка позволяет отправлять несколько запросов вместе для асинхронной обработки. Этот шаблон особенно полезен, когда:

* Вам нужно обработать большие объёмы данных
* Немедленные ответы не требуются
* Вы хотите оптимизировать затраты
* Вы проводите масштабные оценки или анализ

Message Batches API реализует этот шаблон.

# Message Batches API

Message Batches API — это мощный и экономичный способ асинхронной обработки больших объёмов запросов [Messages](https://platform.claude.com/docs/ru/api/messages/create). Этот подход хорошо подходит для задач, не требующих немедленных ответов: большинство пакетов завершается менее чем за 1 час, при этом затраты сокращаются на 50 процентов, а пропускная способность увеличивается.

Помимо этого руководства, вы можете [изучить справочник API напрямую](https://platform.claude.com/docs/ru/api/messages/batches/create).

## Как работает Message Batches API

Когда вы отправляете запрос в Message Batches API:

1. Система создаёт новый пакет сообщений с предоставленными запросами Messages.
2. Затем пакет обрабатывается асинхронно, причём каждый запрос обрабатывается независимо.
3. Вы можете опрашивать статус пакета и получать результаты, когда обработка всех запросов завершится.

Это особенно полезно для массовых операций, не требующих немедленных результатов, например:

* Масштабные оценки: эффективно обрабатывайте тысячи тестовых случаев.
* Модерация контента: асинхронно анализируйте большие объёмы пользовательского контента.
* Анализ данных: генерируйте выводы или сводки для больших наборов данных.
* Массовая генерация контента: создавайте большие объёмы текста для различных целей (например, описания товаров, краткие изложения статей).

### Ограничения пакетов

* Пакет сообщений ограничен либо 100 000 запросов Message, либо размером 256 МБ, в зависимости от того, что будет достигнуто первым.
* Система обрабатывает каждый пакет максимально быстро, и большинство пакетов завершается в течение 1 часа. Вы можете получить доступ к результатам пакета, когда все сообщения будут обработаны, или по истечении 24 часов, в зависимости от того, что наступит раньше. Срок действия пакетов истекает, если обработка не завершается в течение 24 часов.
* Результаты пакета доступны в течение 29 дней после создания. После этого вы по-прежнему можете просматривать пакет, но его результаты больше не доступны для загрузки.
* Пакеты ограничены рамками [рабочего пространства в Claude Console](https://platform.claude.com/settings/workspaces). Вы можете просматривать все пакеты (и их результаты), созданные в рабочем пространстве, в котором выполняется ваш запрос.
* Ограничения скорости применяются как к HTTP-запросам Batches API, так и к количеству запросов в пакете, ожидающих обработки. См. [ограничения скорости Message Batches API](https://platform.claude.com/docs/ru/api/rate-limits#message-batches-api). Кроме того, обработка может замедлиться в зависимости от текущей нагрузки и объёма ваших запросов. В этом случае вы можете увидеть больше запросов, срок действия которых истёк через 24 часа.
* Из-за высокой пропускной способности и параллельной обработки пакеты могут немного превысить [лимит расходов](https://platform.claude.com/docs/ru/manage-claude/workspaces#setting-workspace-limits), настроенный в Claude Console для вашего рабочего пространства.
* Каждый запрос в пакете должен иметь [`max_tokens`](https://platform.claude.com/docs/ru/api/messages/create#create.max_tokens) не менее `1`. `max_tokens: 0` ([предварительный прогрев кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#pre-warming-the-cache)) не поддерживается внутри пакета, поскольку эфемерная запись кэша, созданная во время пакетной обработки, скорее всего истечёт до выполнения последующего запроса.

### Поддерживаемые модели

Все [активные модели](https://platform.claude.com/docs/ru/models/overview) поддерживают Message Batches API.

### Что можно обрабатывать пакетно

Почти любой запрос, который вы можете сделать к Messages API, можно включить в пакет. Это включает:

* Обработку изображений (Vision)
* Использование инструментов, включая все [серверные инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools) (веб-поиск, веб-загрузка, выполнение кода, коннекторы MCP, советник и поиск инструментов)
* Системные сообщения
* Многоходовые диалоги
* Расширенные размышления
* Большинство бета-функций

Поскольку каждый запрос в пакете обрабатывается независимо, вы можете смешивать разные типы запросов в одном пакете.

Небольшое количество параметров Messages API **не** поддерживается в пакетных запросах. Включение любого из них возвращает ошибку валидации:

| Параметр                                                                                                                                      | Причина                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stream: true`                                                                                                                                | Результаты пакета возвращаются одним файлом, а не потоком.                                                                                                                                                                          |
| `speed` ([Быстрый режим](https://platform.claude.com/docs/ru/build-with-claude/fast-mode))                                                    | Быстрый режим настраивает задержку синхронных запросов, что неприменимо к асинхронной пакетной обработке.                                                                                                                           |
| `fallbacks` ([Серверный резервный вариант](https://platform.claude.com/docs/ru/build-with-claude/refusals-and-fallback#server-side-fallback)) | Серверный резервный вариант не применяется к пакетам. Чтобы повторить отклонённые запросы, см. [Отказы в Message Batches](https://platform.claude.com/docs/ru/build-with-claude/refusals-and-fallback#refusals-in-message-batches). |
| `max_tokens: 0`                                                                                                                               | См. [Ограничения пакетов](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#batch-limitations).                                                                                                                |

<Tip>
  Поскольку обработка пакетов может занимать более 5 минут, рассмотрите возможность использования [1-часовой длительности кэша](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#1-hour-cache-duration) с кэшированием подсказок для повышения частоты попаданий в кэш при обработке пакетов с общим контекстом.
</Tip>

## Цены

Batches API обеспечивает значительную экономию средств. Всё использование оплачивается по цене 50 процентов от стандартных цен API.

| Model                                                                                                                                                                  | Batch input  | Batch output  |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------ |
| Claude Fable 5.2                                                                                                                                                       | $4 / MTok    | $20 / MTok    |
| Claude Mythos 5.2 ([limited availability](https://support.claude.com/en/articles/14604842))                                                                            | $4 / MTok    | $20 / MTok    |
| Claude Fable 5.1                                                                                                                                                       | $5 / MTok    | $25 / MTok    |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842))                                                                            | $5 / MTok    | $25 / MTok    |
| Claude Fable 5                                                                                                                                                         | $5 / MTok    | $25 / MTok    |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842))                                                                              | $5 / MTok    | $25 / MTok    |
| Claude Opus 5.5                                                                                                                                                        | $2 / MTok    | $10 / MTok    |
| Claude Opus 5                                                                                                                                                          | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.8                                                                                                                                                        | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.7                                                                                                                                                        | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.6                                                                                                                                                        | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.5                                                                                                                                                        | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.1 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ru/about-claude/model-deprecations))               | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 5.5                                                                                                                                                      | $1 / MTok    | $5 / MTok     |
| Claude Sonnet 5                                                                                                                                                        | $1 / MTok    | $5 / MTok     |
| Claude Sonnet 4.6                                                                                                                                                      | $1.50 / MTok | $7.50 / MTok  |
| Claude Sonnet 4.5                                                                                                                                                      | $1.50 / MTok | $7.50 / MTok  |
| Claude Sonnet 4 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/ru/about-claude/model-deprecations)) | $1.50 / MTok | $7.50 / MTok  |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens)                                                                                                                    | $0.05 / MTok | $0.25 / MTok  |
| Claude Haiku 5.5 (for prompts over 100,000 tokens)                                                                                                                     | $0.25 / MTok | $1.25 / MTok  |
| Claude Haiku 4.5                                                                                                                                                       | $0.50 / MTok | $2.50 / MTok  |

* **MTok:** Million tokens. $5 / MTok is $5 for every million tokens.
* **Limited access:** Available only to organizations verified through Anthropic’s verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). To request access, apply to the program that covers your use case.
* **Retired:** May still be available on other cloud platforms. See [Model deprecations](https://platform.claude.com/docs/ru/about-claude/model-deprecations) for more.

## Как использовать Message Batches API

### Подготовка и создание пакета

Пакет сообщений состоит из списка запросов на создание Message. Отдельный запрос включает:

* Уникальный [`custom_id`](https://platform.claude.com/docs/ru/api/messages/batches/create#create.requests.custom_id) для идентификации запроса Messages. Должен содержать от 1 до 64 символов и состоять только из буквенно-цифровых символов, дефисов и подчёркиваний (соответствовать `^[a-zA-Z0-9_-]{1,64}$`).
* Объект [`params`](https://platform.claude.com/docs/ru/api/messages/batches/create#create.requests.params) со стандартными параметрами [Messages API](https://platform.claude.com/docs/ru/api/messages/create)

Вы можете [создать пакет](https://platform.claude.com/docs/ru/api/messages/batches/create), передав этот список в параметр `requests`:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages/batches \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "requests": [
        {
          "custom_id": "my-first-request",
          "params": {
            "model": "claude-opus-5-5",
            "max_tokens": 1024,
            "messages": [
              {"role": "user", "content": "Hello, world"}
            ]
          }
        },
        {
          "custom_id": "my-second-request",
          "params": {
            "model": "claude-opus-5-5",
            "max_tokens": 1024,
            "messages": [
              {"role": "user", "content": "Hi again, friend"}
            ]
          }
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages:batches create <<'YAML'
  requests:
    - custom_id: my-first-request
      params:
        model: claude-opus-5-5
        max_tokens: 1024
        messages:
          - role: user
            content: Hello, world
    - custom_id: my-second-request
      params:
        model: claude-opus-5-5
        max_tokens: 1024
        messages:
          - role: user
            content: Hi again, friend
  YAML
  ```

  ```python Python
  from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
  from anthropic.types.messages.batch_create_params import Request

  client = anthropic.Anthropic()

  message_batch = client.messages.batches.create(
      requests=[
          Request(
              custom_id="my-first-request",
              params=MessageCreateParamsNonStreaming(
                  model="claude-opus-5-5",
                  max_tokens=1024,
                  messages=[
                      {
                          "role": "user",
                          "content": "Hello, world",
                      }
                  ],
              ),
          ),
          Request(
              custom_id="my-second-request",
              params=MessageCreateParamsNonStreaming(
                  model="claude-opus-5-5",
                  max_tokens=1024,
                  messages=[
                      {
                          "role": "user",
                          "content": "Hi again, friend",
                      }
                  ],
              ),
          ),
      ]
  )

  print(message_batch)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const messageBatch = await client.messages.batches.create({
    requests: [
      {
        custom_id: "my-first-request",
        params: {
          model: "claude-opus-5-5",
          max_tokens: 1024,
          messages: [{ role: "user", content: "Hello, world" }]
        }
      },
      {
        custom_id: "my-second-request",
        params: {
          model: "claude-opus-5-5",
          max_tokens: 1024,
          messages: [{ role: "user", content: "Hi again, friend" }]
        }
      }
    ]
  });

  console.log(messageBatch);
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Messages;
  using Anthropic.Models.Messages.Batches;

  AnthropicClient client = new();

  var batch = await client.Messages.Batches.Create(new BatchCreateParams
  {
      Requests =
      [
          new()
          {
              CustomID = "my-first-request",
              Params = new()
              {
                  Model = Model.ClaudeOpus5_5,
                  MaxTokens = 1024,
                  Messages = [new UserMessageParam { Content = "Hello, world" }]
              }
          },
          new()
          {
              CustomID = "my-second-request",
              Params = new()
              {
                  Model = Model.ClaudeOpus5_5,
                  MaxTokens = 1024,
                  Messages = [new UserMessageParam { Content = "Hi again, friend" }]
              }
          }
      ]
  });

  Console.WriteLine(batch);
  ```

  ```go Go
  client := anthropic.NewClient()

  batch, _ := client.Messages.Batches.New(context.Background(),
  	anthropic.MessageBatchNewParams{
  		Requests: []anthropic.MessageBatchNewParamsRequest{
  			{
  				CustomID: "my-first-request",
  				Params: anthropic.MessageBatchNewParamsRequestParams{
  					Model:     anthropic.ModelClaudeOpus5_5,
  					MaxTokens: 1024,
  					Messages: []anthropic.MessageParam{
  						anthropic.NewUserMessage(
  							anthropic.NewTextBlock("Hello, world"),
  						),
  					},
  				},
  			},
  			{
  				CustomID: "my-second-request",
  				Params: anthropic.MessageBatchNewParamsRequestParams{
  					Model:     anthropic.ModelClaudeOpus5_5,
  					MaxTokens: 1024,
  					Messages: []anthropic.MessageParam{
  						anthropic.NewUserMessage(
  							anthropic.NewTextBlock("Hi again, friend"),
  						),
  					},
  				},
  			},
  		},
  	})

  fmt.Println(batch.ID)
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  BatchCreateParams params = BatchCreateParams.builder()
      .addRequest(
          BatchCreateParams.Request.builder()
              .customId("my-first-request")
              .params(
                  BatchCreateParams.Request.Params.builder()
                      .model(Model.CLAUDE_OPUS_5_5)
                      .maxTokens(1024)
                      .addUserMessage("Hello, world")
                      .build()
              )
              .build()
      )
      .addRequest(
          BatchCreateParams.Request.builder()
              .customId("my-second-request")
              .params(
                  BatchCreateParams.Request.Params.builder()
                      .model(Model.CLAUDE_OPUS_5_5)
                      .maxTokens(1024)
                      .addUserMessage("Hi again, friend")
                      .build()
              )
              .build()
      )
      .build();

  MessageBatch messageBatch = client.messages().batches().create(params);

  System.out.println(messageBatch);
  ```

  ```php PHP
  $client = new Client();

  $batch = $client->messages->batches->create(
      requests: [
          [
              'custom_id' => 'my-first-request',
              'params' => [
                  'model' => 'claude-opus-5-5',
                  'max_tokens' => 1024,
                  'messages' => [
                      ['role' => 'user', 'content' => 'Hello, world']
                  ]
              ]
          ],
          [
              'custom_id' => 'my-second-request',
              'params' => [
                  'model' => 'claude-opus-5-5',
                  'max_tokens' => 1024,
                  'messages' => [
                      ['role' => 'user', 'content' => 'Hi again, friend']
                  ]
              ]
          ]
      ],
  );

  echo $batch->id;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  batch = client.messages.batches.create(
    requests: [
      {
        custom_id: "my-first-request",
        params: {
          model: Anthropic::Model::CLAUDE_OPUS_5_5,
          max_tokens: 1024,
          messages: [
            { role: "user", content: "Hello, world" }
          ]
        }
      },
      {
        custom_id: "my-second-request",
        params: {
          model: Anthropic::Model::CLAUDE_OPUS_5_5,
          max_tokens: 1024,
          messages: [
            { role: "user", content: "Hi again, friend" }
          ]
        }
      }
    ]
  )

  puts batch
  ```
</CodeGroup>

В этом примере два отдельных запроса объединены в пакет для асинхронной обработки. Каждый запрос имеет уникальный `custom_id` и содержит стандартные параметры, которые вы использовали бы для вызова Messages API.

<Tip>
  **Протестируйте свои пакетные запросы с помощью Messages API**

  API выполняет валидацию объекта `params` каждого запроса сообщения асинхронно и возвращает ошибки валидации после завершения обработки всего пакета. Чтобы убедиться, что вы правильно формируете входные данные, предварительно проверьте структуру запроса с помощью [Messages API](https://platform.claude.com/docs/ru/api/messages/create).
</Tip>

При первом создании пакета ответ имеет статус обработки `in_progress`.

```json Output
{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}
```

### Отслеживание пакета

Поле [`processing_status`](https://platform.claude.com/docs/ru/api/messages/batches/retrieve#message_batch.processing_status) в пакете сообщений указывает, на каком этапе обработки находится пакет. Изначально оно имеет значение `in_progress`, затем обновляется до `ended`, когда все запросы в пакете завершили обработку и результаты готовы. Вы можете отслеживать состояние пакета в [Console](https://platform.claude.com/settings/workspaces/default/batches) или с помощью эндпоинта получения.

(See the `messages/batches/retrieve` method in [the API reference](https://platform.claude.com/docs/ru/api/messages/batches/retrieve).)

#### Опрос завершения пакета сообщений

Чтобы опрашивать пакет сообщений, вам понадобится его `id`, который предоставляется в ответе при создании пакета или при получении списка пакетов. Вы можете реализовать цикл опроса, который периодически проверяет статус пакета до завершения обработки:

<CodeGroup>
  ```bash cURL
  # Проверьте статус; повторяйте, пока processing_status не станет "ended"
  curl "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21"
  ```

  ```bash CLI
  # Проверьте статус; повторяйте, пока processing_status не станет "ended"
  ant messages:batches retrieve --message-batch-id "$MESSAGE_BATCH_ID"
  ```

  ```python Python
  import time

  client = anthropic.Anthropic()

  MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

  message_batch = None
  while True:
      message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
      if message_batch.processing_status == "ended":
          break

      print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
      time.sleep(60)
  print(message_batch)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";

  let messageBatch;
  while (true) {
    messageBatch = await client.messages.batches.retrieve(messageBatchId);
    if (messageBatch.processing_status === "ended") {
      break;
    }

    console.log(`Batch ${messageBatchId} is still processing... waiting`);
    await new Promise((resolve) => setTimeout(resolve, 60_000));
  }
  console.log(messageBatch);
  ```

  ```csharp C#
  AnthropicClient client = new();
  string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");

  MessageBatch messageBatch = null;
  while (true)
  {
      messageBatch = await client.Messages.Batches.Retrieve(messageBatchId);
      if (messageBatch.ProcessingStatus == "ended")
      {
          break;
      }

      Console.WriteLine($"Batch {messageBatchId} is still processing...");
      await Task.Delay(60000);
  }
  Console.WriteLine(messageBatch);
  ```

  ```go Go
  client := anthropic.NewClient()
  messageBatchID := os.Getenv("MESSAGE_BATCH_ID")

  var messageBatch *anthropic.MessageBatch
  for {
  	var err error
  	messageBatch, err = client.Messages.Batches.Get(context.TODO(), messageBatchID, anthropic.MessageBatchGetParams{})
  	if err != nil {
  		log.Fatal(err)
  	}
  	if messageBatch.ProcessingStatus == "ended" {
  		break
  	}

  	fmt.Printf("Batch %s is still processing...\n", messageBatchID)
  	time.Sleep(60 * time.Second)
  }
  fmt.Println(messageBatch)
  ```

  ```java Java
  import com.anthropic.models.messages.batches.MessageBatch;
  // ...
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();
          String messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";

          MessageBatch messageBatch = null;
          while (true) {
              messageBatch = client.messages().batches().retrieve(messageBatchId);
              if (messageBatch.processingStatus().equals(MessageBatch.ProcessingStatus.ENDED)) {
                  break;
              }

              System.out.println("Batch " + messageBatchId + " is still processing...");
              Thread.sleep(60000);
          }
          System.out.println(messageBatch);
  ```

  ```php PHP
  $client = new Client();
  $messageBatchId = getenv('MESSAGE_BATCH_ID');

  $messageBatch = null;
  while (true) {
      $messageBatch = $client->messages->batches->retrieve(
          messageBatchID: $messageBatchId,
      );
      if ($messageBatch->processingStatus === 'ended') {
          break;
      }

      echo "Batch {$messageBatchId} is still processing...\n";
      sleep(60);
  }
  echo json_encode($messageBatch, JSON_PRETTY_PRINT);
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message_batch_id = ENV["MESSAGE_BATCH_ID"]
  message_batch = nil
  loop do
    message_batch = client.messages.batches.retrieve(message_batch_id)
    break if message_batch.processing_status == :ended

    puts "Batch #{message_batch_id} is still processing..."
    sleep 60
  end
  puts message_batch
  ```
</CodeGroup>

### Получение списка всех пакетов сообщений

Вы можете получить список всех пакетов сообщений в вашем рабочем пространстве с помощью [эндпоинта списка](https://platform.claude.com/docs/ru/api/messages/batches/list). Результаты разбиваются на страницы. SDK загружает дополнительные страницы по мере необходимости:

<CodeGroup>
  ```bash cURL
  # Получает одну страницу. Пока has_more в ответе равно true, передавайте его
  # last_id как after_id, чтобы получить следующую страницу. (SDK и CLI
  # выполняют пагинацию автоматически.)
  curl -s "https://api.anthropic.com/v1/messages/batches?limit=20" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21"
  ```

  ```bash CLI
  # Автоматически загружает дополнительные страницы по мере необходимости
  ant messages:batches list --limit 20
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Автоматически загружает следующие страницы по мере необходимости.
  for message_batch in client.messages.batches.list(limit=20):
      print(message_batch)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // Автоматически загружает следующие страницы по мере необходимости.
  for await (const messageBatch of client.messages.batches.list({
    limit: 20
  })) {
    console.log(messageBatch);
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new BatchListParams
  {
      Limit = 20
  };

  // Автоматически загружает дополнительные страницы по мере необходимости
  var page = await client.Messages.Batches.List(parameters);
  await foreach (var messageBatch in page.Paginate())
  {
      Console.WriteLine(messageBatch);
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  // Автоматически загружает следующие страницы по мере необходимости
  iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
  	Limit: anthropic.Int(20),
  })

  for iter.Next() {
  	messageBatch := iter.Current()
  	fmt.Println(messageBatch)
  }

  if err := iter.Err(); err != nil {
  	log.Fatal(err)
  }
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Автоматически загружает следующие страницы по мере необходимости
  for (MessageBatch messageBatch : client
      .messages()
      .batches()
      .list(BatchListParams.builder()
          .limit(20)
          .build())
      .autoPager()) {
      System.out.println(messageBatch);
  }
  ```

  ```php PHP
  $client = new Client();

  // Автоматически загружает следующие страницы по мере необходимости
  foreach ($client->messages->batches->list(limit: 20)->pagingEachItem() as $messageBatch) {
      echo $messageBatch->id . "\n";
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Автоматически загружает дополнительные страницы по мере необходимости
  client.messages.batches.list(limit: 20).auto_paging_each do |message_batch|
    puts message_batch
  end
  ```
</CodeGroup>

### Получение результатов пакета

После завершения обработки пакета каждый запрос Messages в пакете имеет результат. Существует четыре типа результатов:

| Тип результата | Описание                                                                                                                                                                               |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `succeeded`    | Запрос выполнен успешно. Включает результат сообщения.                                                                                                                                 |
| `errored`      | При выполнении запроса произошла ошибка, и сообщение не было создано. Возможные ошибки включают недопустимые запросы и внутренние ошибки сервера. Плата за такие запросы не взимается. |
| `canceled`     | Пользователь отменил пакет до того, как этот запрос был отправлен модели. Плата за такие запросы не взимается.                                                                         |
| `expired`      | Срок действия пакета (24 часа) истёк до того, как этот запрос был отправлен модели. Плата за такие запросы не взимается.                                                               |

Объект `request_counts` пакета подсчитывает запросы, которые всё ещё обрабатываются, и запросы с каждым типом результата.

(See `message_batch.request_counts` on `messages/batches/retrieve` in [the API reference](https://platform.claude.com/docs/ru/api/messages/batches/retrieve#message_batch.request_counts).)

Результаты пакета доступны для загрузки по свойству [`results_url`](https://platform.claude.com/docs/ru/api/messages/batches/retrieve#message_batch.results_url) в пакете сообщений, а также, если это разрешено правами вашей организации, в Console. Поскольку результаты могут быть большими, [получайте результаты потоком](https://platform.claude.com/docs/ru/api/messages/batches/results), а не загружайте их все сразу.

<CodeGroup>
  ```bash cURL
  # Передаёт результаты пакета в формате .jsonl в режиме потоковой передачи, по одному результату на строку.
  # Для обработки отдельных результатов (повторы, ошибки валидации) используйте Anthropic SDK.
  curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d/results" \
    -H "anthropic-version: 2026-10-21" \
    -H "x-api-key: $ANTHROPIC_API_KEY"
  ```

  ```bash CLI
  # Выводит по одному результату в строке, например `{"custom_id":"test-1","result":{"type":"succeeded",…}}`.
  # Для обработки отдельных результатов (повторы, ошибки валидации) используйте Anthropic SDK —
  # см. примеры на других вкладках.
  ant messages:batches results \
    --message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
    --format jsonl
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Потоковое чтение файла результатов экономными по памяти частями, по одной за раз
  for result in client.messages.batches.results(
      "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  ):
      outcome = result.result
      match outcome.type:
          case "succeeded":
              print(f"Success! {result.custom_id}")
          case "errored":
              if outcome.error.error.type == "invalid_request_error":
                  # Перед повторной отправкой запроса необходимо исправить его тело
                  print(f"Validation error {result.custom_id}")
              else:
                  # Запрос можно повторить без изменений
                  print(f"Server error {result.custom_id}")
          case "expired":
              print(f"Request expired {result.custom_id}")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // Потоковая передача файла результатов экономными по памяти фрагментами, по одному за раз
  for await (const result of await client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
  )) {
    switch (result.result.type) {
      case "succeeded":
        console.log(`Success! ${result.custom_id}`);
        break;
      case "errored":
        if (result.result.error.error.type === "invalid_request_error") {
          // Тело запроса необходимо исправить перед повторной отправкой
          console.log(`Validation error: ${result.custom_id}`);
        } else {
          // Запрос можно повторить напрямую
          console.log(`Server error: ${result.custom_id}`);
        }
        break;
      case "expired":
        console.log(`Request expired: ${result.custom_id}`);
        break;
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  await foreach (var result in client.Messages.Batches.ResultsStreaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"))
  {
      switch (result.Result.Type.Raw())
      {
          case "succeeded":
              Console.WriteLine($"Success! {result.CustomID}");
              break;
          case "errored":
              if (result.Result.TryPickErrored(out var errored)
                  && errored.Error.Error.Type.Raw() == "invalid_request_error")
              {
                  Console.WriteLine($"Validation error: {result.CustomID}");
              }
              else
              {
                  Console.WriteLine($"Server error: {result.CustomID}");
              }
              break;
          case "expired":
              Console.WriteLine($"Request expired: {result.CustomID}");
              break;
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  stream := client.Messages.Batches.ResultsStreaming(context.TODO(), "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d", anthropic.MessageBatchResultsParams{})

  for stream.Next() {
  	result := stream.Current()

  	switch variant := result.Result.AsAny().(type) {
  	case anthropic.MessageBatchSucceededResult:
  		fmt.Printf("Success! %s\n", result.CustomID)
  	case anthropic.MessageBatchErroredResult:
  		fmt.Printf("Error: %s - %s\n", result.CustomID, variant.Error.Error.Message)
  	case anthropic.MessageBatchExpiredResult:
  		fmt.Printf("Request expired: %s\n", result.CustomID)
  	}
  }

  if err := stream.Err(); err != nil {
  	log.Fatal(err)
  }
  ```

  ```java Java
  import com.anthropic.core.http.StreamResponse;
  import com.anthropic.models.messages.batches.BatchResultsParams;
  import com.anthropic.models.messages.batches.MessageBatchIndividualResponse;
  // ...
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          // Потоковое чтение файла результатов экономными по памяти частями, по одной за раз
          try (
              StreamResponse<MessageBatchIndividualResponse> streamResponse = client
                  .messages()
                  .batches()
                  .resultsStreaming(
                      BatchResultsParams.builder()
                          .messageBatchId("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d")
                          .build()
                  )
          ) {
              streamResponse
                  .stream()
                  .forEach(result -> {
                      switch (result.result().type().value()) {
                          case SUCCEEDED -> System.out.println("Success! " + result.customId());
                          case ERRORED -> {
                              if (result.result().asErrored().error().error().isInvalidRequestError()) {
                                  // Перед повторной отправкой запроса необходимо исправить тело запроса
                                  System.out.println("Validation error: " + result.customId());
                              } else {
                                  // Запрос можно повторить напрямую
                                  System.out.println("Server error: " + result.customId());
                              }
                          }
                          case EXPIRED -> System.out.println("Request expired: " + result.customId());
                      }
                  });
          }
  ```

  ```php PHP
  use Anthropic\Messages\Batches\MessageBatchErroredResult;
  use Anthropic\Messages\Batches\MessageBatchExpiredResult;
  use Anthropic\Messages\Batches\MessageBatchSucceededResult;

  $client = new Client();

  foreach ($client->messages->batches->resultsStream(messageBatchID: 'msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d') as $result) {
      switch (true) {
          case $result->result instanceof MessageBatchSucceededResult:
              echo "Success! {$result->customID}\n";
              break;
          case $result->result instanceof MessageBatchErroredResult:
              if ($result->result->error->error->type === 'invalid_request_error') {
                  echo "Validation error: {$result->customID}\n";
              } else {
                  echo "Server error: {$result->customID}\n";
              }
              break;
          case $result->result instanceof MessageBatchExpiredResult:
              echo "Request expired: {$result->customID}\n";
              break;
      }
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  client.messages.batches.results_streaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d").each do |result|
    outcome = result.result
    case outcome
    when Anthropic::Models::Messages::MessageBatchSucceededResult
      puts "Success! #{result.custom_id}"
    when Anthropic::Models::Messages::MessageBatchErroredResult
      if outcome.error.error.type == :invalid_request_error
        puts "Validation error: #{result.custom_id}"
      else
        puts "Server error: #{result.custom_id}"
      end
    when Anthropic::Models::Messages::MessageBatchExpiredResult
      puts "Request expired: #{result.custom_id}"
    end
  end
  ```
</CodeGroup>

Результаты представлены в формате `.jsonl`, где каждая строка — это корректный объект JSON, представляющий результат одного запроса в пакете сообщений. Для каждого полученного потоком результата вы можете выполнять разные действия в зависимости от его `custom_id` и типа результата. Вот пример набора результатов:

```jsonl .jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-5","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-5-5","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}
```

Если ваш результат содержит ошибку, его `result.error` будет иметь стандартную [структуру ошибки](https://platform.claude.com/docs/ru/api/errors#error-shapes).

Результаты пакета используют версию API запроса, который создал пакет.

<Tip>
  **Результаты пакета могут не совпадать с порядком входных данных**

  Результаты пакета могут возвращаться в любом порядке и могут не совпадать с порядком запросов при создании пакета. В предыдущем примере результат второго запроса пакета возвращается раньше первого. Чтобы правильно сопоставлять результаты с соответствующими запросами, всегда используйте поле `custom_id`.
</Tip>

### Отмена пакета сообщений

Вы можете отменить пакет сообщений, который находится в процессе обработки, с помощью [эндпоинта отмены](https://platform.claude.com/docs/ru/api/messages/batches/cancel). Сразу после отмены `processing_status` пакета имеет значение `canceling`. Вы можете использовать описанный ранее способ опроса, чтобы дождаться завершения отмены. Отменённые пакеты в итоге получают статус `ended` и могут содержать частичные результаты для запросов, обработанных до отмены.

<CodeGroup>
  ```bash cURL
  curl -X POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21"
  ```

  ```bash CLI
  ant messages:batches cancel --message-batch-id "$MESSAGE_BATCH_ID"
  ```

  ```python Python
  client = anthropic.Anthropic()

  MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

  message_batch = client.messages.batches.cancel(
      MESSAGE_BATCH_ID,
  )
  print(message_batch)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const messageBatch = await client.messages.batches.cancel(MESSAGE_BATCH_ID);
  console.log(messageBatch);
  ```

  ```csharp C#
  AnthropicClient client = new();
  string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");

  var messageBatch = await client.Messages.Batches.Cancel(messageBatchId);
  Console.WriteLine(messageBatch);
  ```

  ```go Go
  client := anthropic.NewClient()
  messageBatchID := os.Getenv("MESSAGE_BATCH_ID")

  messageBatch, err := client.Messages.Batches.Cancel(context.TODO(), messageBatchID, anthropic.MessageBatchCancelParams{})
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(messageBatch)
  ```

  ```java Java
  import com.anthropic.models.messages.batches.*;
  // ...
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          MessageBatch messageBatch = client
              .messages()
              .batches()
              .cancel("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d");
          System.out.println(messageBatch);
  ```

  ```php PHP
  $client = new Client();

  $messageBatch = $client->messages->batches->cancel(
      messageBatchID: 'msgbatch_example_id',
  );
  echo $messageBatch;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message_batch_id = ENV.fetch("MESSAGE_BATCH_ID")
  message_batch = client.messages.batches.cancel(message_batch_id)
  puts message_batch
  ```
</CodeGroup>

Ответ показывает пакет в состоянии `canceling`:

```json Output
{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}
```

### Использование кэширования подсказок с Message Batches

Message Batches API поддерживает «prompt caching» (кэширование подсказок), что позволяет потенциально снизить затраты и время обработки пакетных запросов. Скидки от кэширования подсказок и Message Batches могут суммироваться, обеспечивая ещё большую экономию при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш обеспечиваются по принципу наилучших усилий. Обычно частота попаданий в кэш у пользователей составляет от 30 до 98 процентов в зависимости от характера их трафика.

Чтобы максимально повысить вероятность попаданий в кэш в пакетных запросах:

1. Включайте идентичные блоки `cache_control` в каждый запрос Message в пакете.
2. Поддерживайте стабильный поток запросов, чтобы записи кэша не истекали по окончании их 5-минутного срока жизни.
3. Структурируйте запросы так, чтобы они совместно использовали как можно больше кэшированного контента.

Пример реализации кэширования подсказок в пакете:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages/batches \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "requests": [
        {
          "custom_id": "my-first-request",
          "params": {
            "model": "claude-opus-5-5",
            "max_tokens": 1024,
            "system": [
              {
                "type": "text",
                "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
              },
              {
                "type": "text",
                "text": "<the entire contents of Pride and Prejudice>",
                "cache_control": {"type": "ephemeral"}
              }
            ],
            "messages": [
              {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
            ]
          }
        },
        {
          "custom_id": "my-second-request",
          "params": {
            "model": "claude-opus-5-5",
            "max_tokens": 1024,
            "system": [
              {
                "type": "text",
                "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
              },
              {
                "type": "text",
                "text": "<the entire contents of Pride and Prejudice>",
                "cache_control": {"type": "ephemeral"}
              }
            ],
            "messages": [
              {"role": "user", "content": "Write a summary of Pride and Prejudice."}
            ]
          }
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages:batches create <<'YAML'
  requests:
    - custom_id: my-first-request
      params:
        model: claude-opus-5-5
        max_tokens: 1024
        system:
          - type: text
            text: >
              You are an AI assistant tasked with analyzing literary works. Your
              goal is to provide insightful commentary on themes, characters, and
              writing style.
          - type: text
            text: "<the entire contents of Pride and Prejudice>"
            cache_control:
              type: ephemeral
        messages:
          - role: user
            content: Analyze the major themes in Pride and Prejudice.
    - custom_id: my-second-request
      params:
        model: claude-opus-5-5
        max_tokens: 1024
        system:
          - type: text
            text: >
              You are an AI assistant tasked with analyzing literary works. Your
              goal is to provide insightful commentary on themes, characters, and
              writing style.
          - type: text
            text: "<the entire contents of Pride and Prejudice>"
            cache_control:
              type: ephemeral
        messages:
          - role: user
            content: Write a summary of Pride and Prejudice.
  YAML
  ```

  ```python Python
  from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
  from anthropic.types.messages.batch_create_params import Request

  client = anthropic.Anthropic()

  message_batch = client.messages.batches.create(
      requests=[
          Request(
              custom_id="my-first-request",
              params=MessageCreateParamsNonStreaming(
                  model="claude-opus-5-5",
                  max_tokens=1024,
                  system=[
                      {
                          "type": "text",
                          "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
                      },
                      {
                          "type": "text",
                          "text": "<the entire contents of Pride and Prejudice>",
                          "cache_control": {"type": "ephemeral"},
                      },
                  ],
                  messages=[
                      {
                          "role": "user",
                          "content": "Analyze the major themes in Pride and Prejudice.",
                      }
                  ],
              ),
          ),
          Request(
              custom_id="my-second-request",
              params=MessageCreateParamsNonStreaming(
                  model="claude-opus-5-5",
                  max_tokens=1024,
                  system=[
                      {
                          "type": "text",
                          "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
                      },
                      {
                          "type": "text",
                          "text": "<the entire contents of Pride and Prejudice>",
                          "cache_control": {"type": "ephemeral"},
                      },
                  ],
                  messages=[
                      {
                          "role": "user",
                          "content": "Write a summary of Pride and Prejudice.",
                      }
                  ],
              ),
          ),
      ]
  )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const messageBatch = await client.messages.batches.create({
    requests: [
      {
        custom_id: "my-first-request",
        params: {
          model: "claude-opus-5-5",
          max_tokens: 1024,
          system: [
            {
              type: "text",
              text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
            },
            {
              type: "text",
              text: "<the entire contents of Pride and Prejudice>",
              cache_control: { type: "ephemeral" }
            }
          ],
          messages: [
            { role: "user", content: "Analyze the major themes in Pride and Prejudice." }
          ]
        }
      },
      {
        custom_id: "my-second-request",
        params: {
          model: "claude-opus-5-5",
          max_tokens: 1024,
          system: [
            {
              type: "text",
              text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
            },
            {
              type: "text",
              text: "<the entire contents of Pride and Prejudice>",
              cache_control: { type: "ephemeral" }
            }
          ],
          messages: [{ role: "user", content: "Write a summary of Pride and Prejudice." }]
        }
      }
    ]
  });
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Messages;
  using Anthropic.Models.Messages.Batches;

  AnthropicClient client = new()
  {
      ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
  };

  var messageBatch = await client.Messages.Batches.Create(new BatchCreateParams
  {
      Requests =
      [
          new()
          {
              CustomID = "my-first-request",
              Params = new()
              {
                  Model = Model.ClaudeOpus5_5,
                  MaxTokens = 1024,
                  System = new List<TextBlockParam>
                  {
                      new()
                      {
                          Text = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                      },
                      new()
                      {
                          Text = "<the entire contents of Pride and Prejudice>",
                          CacheControl = new()
                      }
                  },
                  Messages =
                  [
                      new UserMessageParam { Content = "Analyze the major themes in Pride and Prejudice." }
                  ]
              }
          },
          new()
          {
              CustomID = "my-second-request",
              Params = new()
              {
                  Model = Model.ClaudeOpus5_5,
                  MaxTokens = 1024,
                  System = new List<TextBlockParam>
                  {
                      new()
                      {
                          Text = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                      },
                      new()
                      {
                          Text = "<the entire contents of Pride and Prejudice>",
                          CacheControl = new()
                      }
                  },
                  Messages =
                  [
                      new UserMessageParam { Content = "Write a summary of Pride and Prejudice." }
                  ]
              }
          }
      ]
  });
  ```

  ```go Go
  client := anthropic.NewClient()

  messageBatch, err := client.Messages.Batches.New(context.TODO(), anthropic.MessageBatchNewParams{
  	Requests: []anthropic.MessageBatchNewParamsRequest{
  		{
  			CustomID: "my-first-request",
  			Params: anthropic.MessageBatchNewParamsRequestParams{
  				Model:     anthropic.ModelClaudeOpus5_5,
  				MaxTokens: 1024,
  				System: []anthropic.TextBlockParam{
  					{
  						Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
  					},
  					{
  						Text:         "<the entire contents of Pride and Prejudice>",
  						CacheControl: anthropic.NewCacheControlEphemeralParam(),
  					},
  				},
  				Messages: []anthropic.MessageParam{
  					anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in Pride and Prejudice.")),
  				},
  			},
  		},
  		{
  			CustomID: "my-second-request",
  			Params: anthropic.MessageBatchNewParamsRequestParams{
  				Model:     anthropic.ModelClaudeOpus5_5,
  				MaxTokens: 1024,
  				System: []anthropic.TextBlockParam{
  					{
  						Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
  					},
  					{
  						Text:         "<the entire contents of Pride and Prejudice>",
  						CacheControl: anthropic.NewCacheControlEphemeralParam(),
  					},
  				},
  				Messages: []anthropic.MessageParam{
  					anthropic.NewUserMessage(anthropic.NewTextBlock("Write a summary of Pride and Prejudice.")),
  				},
  			},
  		},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(messageBatch)
  ```

  ```java Java
  import com.anthropic.models.messages.CacheControlEphemeral;
  // ...
  import com.anthropic.models.messages.batches.*;
  // ...
          AnthropicClient client = AnthropicOkHttpClient.fromEnv();

          BatchCreateParams createParams = BatchCreateParams.builder()
              .addRequest(
                  BatchCreateParams.Request.builder()
                      .customId("my-first-request")
                      .params(
                          BatchCreateParams.Request.Params.builder()
                              .model(Model.CLAUDE_OPUS_5_5)
                              .maxTokens(1024)
                              .systemOfTextBlockParams(
                                  List.of(
                                      TextBlockParam.builder()
                                          .text(
                                              "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                                          )
                                          .build(),
                                      TextBlockParam.builder()
                                          .text("<the entire contents of Pride and Prejudice>")
                                          .cacheControl(CacheControlEphemeral.builder().build())
                                          .build()
                                  )
                              )
                              .addUserMessage("Analyze the major themes in Pride and Prejudice.")
                              .build()
                      )
                      .build()
              )
              .addRequest(
                  BatchCreateParams.Request.builder()
                      .customId("my-second-request")
                      .params(
                          BatchCreateParams.Request.Params.builder()
                              .model(Model.CLAUDE_OPUS_5_5)
                              .maxTokens(1024)
                              .systemOfTextBlockParams(
                                  List.of(
                                      TextBlockParam.builder()
                                          .text(
                                              "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
                                          )
                                          .build(),
                                      TextBlockParam.builder()
                                          .text("<the entire contents of Pride and Prejudice>")
                                          .cacheControl(CacheControlEphemeral.builder().build())
                                          .build()
                                  )
                              )
                              .addUserMessage("Write a summary of Pride and Prejudice.")
                              .build()
                      )
                      .build()
              )
              .build();

          MessageBatch messageBatch = client.messages().batches().create(createParams);
  ```

  ```php PHP
  $client = new Client();

  $messageBatch = $client->messages->batches->create(
      requests: [
          [
              'custom_id' => 'my-first-request',
              'params' => [
                  'model' => 'claude-opus-5-5',
                  'max_tokens' => 1024,
                  'system' => [
                      [
                          'type' => 'text',
                          'text' => 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n'
                      ],
                      [
                          'type' => 'text',
                          'text' => '<the entire contents of Pride and Prejudice>',
                          'cache_control' => ['type' => 'ephemeral']
                      ]
                  ],
                  'messages' => [
                      ['role' => 'user', 'content' => 'Analyze the major themes in Pride and Prejudice.']
                  ]
              ]
          ],
          [
              'custom_id' => 'my-second-request',
              'params' => [
                  'model' => 'claude-opus-5-5',
                  'max_tokens' => 1024,
                  'system' => [
                      [
                          'type' => 'text',
                          'text' => 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n'
                      ],
                      [
                          'type' => 'text',
                          'text' => '<the entire contents of Pride and Prejudice>',
                          'cache_control' => ['type' => 'ephemeral']
                      ]
                  ],
                  'messages' => [
                      ['role' => 'user', 'content' => 'Write a summary of Pride and Prejudice.']
                  ]
              ]
          ]
      ],
  );
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message_batch = client.messages.batches.create(
    requests: [
      {
        custom_id: "my-first-request",
        params: {
          model: Anthropic::Model::CLAUDE_OPUS_5_5,
          max_tokens: 1024,
          system: [
            {
              type: "text",
              text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
            },
            {
              type: "text",
              text: "<the entire contents of Pride and Prejudice>",
              cache_control: { type: "ephemeral" }
            }
          ],
          messages: [
            { role: "user", content: "Analyze the major themes in Pride and Prejudice." }
          ]
        }
      },
      {
        custom_id: "my-second-request",
        params: {
          model: Anthropic::Model::CLAUDE_OPUS_5_5,
          max_tokens: 1024,
          system: [
            {
              type: "text",
              text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
            },
            {
              type: "text",
              text: "<the entire contents of Pride and Prejudice>",
              cache_control: { type: "ephemeral" }
            }
          ],
          messages: [
            { role: "user", content: "Write a summary of Pride and Prejudice." }
          ]
        }
      }
    ]
  )
  ```
</CodeGroup>

В этом примере оба запроса в пакете включают идентичные системные сообщения и полный текст романа «Гордость и предубеждение», помеченный `cache_control`, чтобы повысить вероятность попаданий в кэш.

### Серверные инструменты и агентный цикл

Все [серверные инструменты](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools) (веб-поиск, веб-загрузка, выполнение кода, коннекторы MCP, советник и поиск инструментов) работают в пакетных запросах. Обработчик пакетов выполняет тот же серверный агентный цикл, что и синхронный Messages API.

Поскольку нет открытого соединения, которое нужно поддерживать, пакетный цикл может выполнить **больше итераций за один ход**, чем синхронный запрос, прежде чем вернуть `stop_reason: "pause_turn"`. Если результат пакета возвращается с `pause_turn`, ход не был завершён; вы можете продолжить его, отправив приостановленный контент ассистента в последующем запросе (пакетном или синхронном) точно так, как показано в [шаблоне продолжения pause\_turn](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn).

Кроме того, обработчик пакетов регулирует интенсивность `web_search` для каждой организации, чтобы высокопараллельная пакетная обработка не исчерпала ограничение скорости веб-поиска вашей организации. Пакет автоматически повторяет регулируемые запросы; вам не нужно обрабатывать это самостоятельно, но очень большие пакеты с веб-поиском могут выполняться дольше.

### Расширенный вывод (бета)

Бета-заголовок `output-300k-2026-03-24` повышает предел `max_tokens` до 300 000 для пакетных запросов, использующих Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 или Claude Haiku 5.5. Включите этот заголовок, чтобы генерировать за один ход выводы, значительно превышающие стандартный лимит `max_tokens` в 128k.

Расширенный вывод доступен только в Message Batches API, но не в синхронном Messages API.

Используйте расширенный вывод для генерации длинных текстов, таких как черновики объёмом с книгу и техническая документация, исчерпывающее извлечение структурированных данных, крупные заготовки при генерации кода и длинные цепочки рассуждений.

Одна генерация объёмом 300k токенов может занять более часа, поэтому планируйте отправку пакетов с учётом 24-часового окна обработки. Применяются стандартные цены на пакеты (50 процентов от стандартных цен API).

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages/batches \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: output-300k-2026-03-24" \
    -H "content-type: application/json" \
    -d '{
      "requests": [
        {
          "custom_id": "long-form-request",
          "params": {
            "model": "claude-opus-5-5",
            "max_tokens": 300000,
            "messages": [
              {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
            ]
          }
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:messages:batches create --beta output-300k-2026-03-24 <<'YAML'
  requests:
    - custom_id: long-form-request
      params:
        model: claude-opus-5-5
        max_tokens: 300000
        messages:
          - role: user
            content: >-
              Write a comprehensive technical guide to building distributed
              systems, covering architecture patterns, consistency models,
              fault tolerance, and operational best practices.
  YAML
  ```

  ```python Python
  from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
  from anthropic.types.beta.messages.batch_create_params import Request

  client = anthropic.Anthropic()

  message_batch = client.beta.messages.batches.create(
      betas=["output-300k-2026-03-24"],
      requests=[
          Request(
              custom_id="long-form-request",
              params=MessageCreateParamsNonStreaming(
                  model="claude-opus-5-5",
                  max_tokens=300_000,
                  messages=[
                      {
                          "role": "user",
                          "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
                      }
                  ],
              ),
          ),
      ],
  )

  print(message_batch)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const messageBatch = await client.beta.messages.batches.create({
    betas: ["output-300k-2026-03-24"],
    requests: [
      {
        custom_id: "long-form-request",
        params: {
          model: "claude-opus-5-5",
          max_tokens: 300000,
          messages: [
            {
              role: "user",
              content:
                "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."
            }
          ]
        }
      }
    ]
  });

  console.log(messageBatch);
  ```

  ```csharp C#
  using Anthropic;
  using Anthropic.Models.Beta.Messages;
  using Anthropic.Models.Beta.Messages.Batches;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var batch = await client.Beta.Messages.Batches.Create(new BatchCreateParams
  {
      Betas = ["output-300k-2026-03-24"],
      Requests =
      [
          new()
          {
              CustomID = "long-form-request",
              Params = new()
              {
                  Model = Model.ClaudeOpus5_5,
                  MaxTokens = 300_000,
                  Messages =
                  [
                      new BetaUserMessageParam { Content = "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }
                  ]
              }
          }
      ]
  });

  Console.WriteLine(batch);
  ```

  ```go Go
  client := anthropic.NewClient()

  batch, err := client.Beta.Messages.Batches.New(context.Background(),
  	anthropic.BetaMessageBatchNewParams{
  		Betas: []anthropic.AnthropicBeta{"output-300k-2026-03-24"},
  		Requests: []anthropic.BetaMessageBatchNewParamsRequest{
  			{
  				CustomID: "long-form-request",
  				Params: anthropic.BetaMessageBatchNewParamsRequestParams{
  					Model:     anthropic.ModelClaudeOpus5_5,
  					MaxTokens: 300_000,
  					Messages: []anthropic.BetaMessageParam{
  						anthropic.NewBetaUserMessage(
  							anthropic.NewBetaTextBlock("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."),
  						),
  					},
  				},
  			},
  		},
  	})
  if err != nil {
  	panic(err)
  }

  fmt.Println(batch.ID)
  ```

  ```java Java
  import com.anthropic.models.beta.messages.batches.*;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      BatchCreateParams params = BatchCreateParams.builder()
          .addBeta("output-300k-2026-03-24")
          .addRequest(
              BatchCreateParams.Request.builder()
                  .customId("long-form-request")
                  .params(
                      BatchCreateParams.Request.Params.builder()
                          .model(Model.CLAUDE_OPUS_5_5)
                          .maxTokens(300_000L)
                          .addUserMessage("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.")
                          .build()
                  )
                  .build()
          )
          .build();

      BetaMessageBatch messageBatch = client.beta().messages().batches().create(params);

      IO.println(messageBatch);
  }
  ```

  ```php PHP
  $client = new Client();

  $batch = $client->beta->messages->batches->create(
      betas: ['output-300k-2026-03-24'],
      requests: [
          [
              'custom_id' => 'long-form-request',
              'params' => [
                  'model' => 'claude-opus-5-5',
                  'max_tokens' => 300_000,
                  'messages' => [
                      ['role' => 'user', 'content' => 'Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.']
                  ]
              ]
          ]
      ],
  );

  echo $batch->id;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  batch = client.beta.messages.batches.create(
    betas: ["output-300k-2026-03-24"],
    requests: [
      {
        custom_id: "long-form-request",
        params: {
          model: Anthropic::Model::CLAUDE_OPUS_5_5,
          max_tokens: 300_000,
          messages: [
            { role: "user", content: "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }
          ]
        }
      }
    ]
  )

  puts batch
  ```
</CodeGroup>

### Рекомендации по эффективной пакетной обработке

Чтобы эффективно использовать Batches API:

* Регулярно отслеживайте статус обработки пакетов и реализуйте соответствующую логику повторных попыток для неудачных запросов.
* Используйте осмысленные значения `custom_id`, чтобы легко сопоставлять результаты с запросами, поскольку порядок не гарантируется.
* Рассмотрите возможность разбиения очень больших наборов данных на несколько пакетов для удобства управления.
* Выполните пробный запуск одной структуры запроса с помощью Messages API, чтобы избежать ошибок валидации.

### Устранение распространённых проблем

При неожиданном поведении:

* Убедитесь, что общий размер пакетного запроса не превышает 256 МБ. Если размер запроса слишком велик, вы можете получить ошибку 413 `request_too_large`.
* Проверьте, что вы используете [поддерживаемые модели](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#supported-models) для всех запросов в пакете.
* Убедитесь, что каждый запрос в пакете имеет уникальный `custom_id`.
* Убедитесь, что с момента `created_at` пакета (а не с момента окончания обработки `ended_at`) прошло менее 29 дней. По истечении 29 дней результаты больше не доступны для загрузки.
* Убедитесь, что пакет не был отменён.

Обратите внимание, что сбой одного запроса в пакете не влияет на обработку других запросов.

## Хранение пакетов и конфиденциальность

* **Изоляция рабочих пространств:** пакеты изолированы в пределах рабочего пространства, в котором они созданы. Доступ к ним возможен только через запросы API в том же рабочем пространстве или пользователям с правами на просмотр пакетов рабочего пространства в Console.

* **Доступность результатов:** результаты пакета доступны в течение 29 дней после создания пакета, что даёт достаточно времени для их получения и обработки.

## Часто задаваемые вопросы

<AccordionGroup>
  <Accordion title="Сколько времени занимает обработка пакета?">
    Обработка пакетов может занимать до 24 часов, но многие завершаются быстрее. Фактическое время обработки зависит от размера пакета, текущей нагрузки и объёма ваших запросов. Возможно, что срок действия пакета истечёт и он не будет завершён в течение 24 часов.
  </Accordion>

  <Accordion title="Доступен ли Batches API для всех моделей?">
    Список поддерживаемых моделей см. в разделе [Поддерживаемые модели](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#supported-models).
  </Accordion>

  <Accordion title="Можно ли использовать Message Batches API с другими функциями API?">
    Да, Message Batches API поддерживает почти все функции, доступные в Messages API, включая большинство бета-функций. Небольшое количество параметров (`stream`, `speed`, `fallbacks` и `max_tokens: 0`) не поддерживается. Полный список см. в разделе [Что можно обрабатывать пакетно](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#what-can-be-batched).
  </Accordion>

  <Accordion title="Как Message Batches API влияет на цены?">
    Message Batches API предоставляет скидку 50 процентов на всё использование по сравнению со стандартными ценами API. Это относится к входным токенам, выходным токенам и любым специальным токенам. Подробнее о ценах см. на странице [Цены](https://claude.com/pricing#anthropic-api).
  </Accordion>

  <Accordion title="Можно ли обновить пакет после его отправки?">
    Нет, после отправки пакет нельзя изменить. Если вам нужно внести изменения, отмените текущий пакет и отправьте новый. Обратите внимание, что отмена может вступить в силу не сразу.
  </Accordion>

  <Accordion title="Есть ли у Message Batches API ограничения скорости и взаимодействуют ли они с ограничениями скорости Messages API?">
    У Message Batches API есть ограничения скорости на основе HTTP-запросов, а также ограничения на количество запросов, ожидающих обработки. См. [ограничения скорости Message Batches API](https://platform.claude.com/docs/ru/api/rate-limits#message-batches-api). Использование Batches API не влияет на ограничения скорости в Messages API.
  </Accordion>

  <Accordion title="Как обрабатывать ошибки в пакетных запросах?">
    При получении результатов каждый запрос имеет поле `result`, указывающее, был ли он `succeeded`, `errored`, `canceled` или `expired`. Для результатов `errored` предоставляется дополнительная информация об ошибке. Объект ответа с ошибкой описан в [справочнике API](https://platform.claude.com/docs/ru/api/messages/batches/create).
  </Accordion>

  <Accordion title="Как Message Batches API обеспечивает конфиденциальность и разделение данных?">
    Message Batches API разработан с надёжными мерами обеспечения конфиденциальности и разделения данных:

    1. Пакеты и их результаты изолированы в пределах рабочего пространства, в котором они были созданы. Это означает, что доступ к ним возможен только через запросы API в том же рабочем пространстве.
    2. Каждый запрос в пакете обрабатывается независимо, без утечки данных между запросами.
    3. Результаты доступны только в течение ограниченного времени (29 дней) и подчиняются [политике хранения данных](https://support.claude.com/en/articles/7996866-how-long-do-you-store-personal-data) Anthropic.
    4. Загрузку результатов пакетов в Console можно отключить на уровне организации или для отдельных рабочих пространств.
  </Accordion>

  <Accordion title="Можно ли использовать кэширование подсказок в Message Batches API?">
    Да, кэширование подсказок можно использовать с Message Batches API. Однако, поскольку асинхронные пакетные запросы могут обрабатываться параллельно и в любом порядке, попадания в кэш обеспечиваются по принципу наилучших усилий.
  </Accordion>
</AccordionGroup>

## Доступность

Пакетная обработка находится в доступе для всех моделей.

### Поддержка API

#### [Messages API](https://platform.claude.com/docs/ru/build-with-claude/working-with-messages)

* Доступность: Доступно

| Статус   | Облачные платформы                                                                                                                                                                                                                                                             |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Доступно | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ru/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |

#### [Managed Agents](https://platform.claude.com/docs/ru/managed-agents/overview)

* Доступность: Недоступно

### Обработка данных

[Обзор обработки данных](https://platform.claude.com/docs/ru/manage-claude/api-and-data-retention#feature-eligibility)

| Элемент     | Нулевое хранение данных                                                                                                                               | HIPAA          |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| Статус      | Не допускается                                                                                                                                        | Не допускается |
| Подробности | Хранение 29 дней; требуется асинхронное хранилище. [Подробнее](https://platform.claude.com/docs/ru/build-with-claude/batch-processing#data-retention) | —              |

Применимые конечные точки:

* `/v1/messages/batches`

Пакетная обработка хранит данные запросов и ответов до 29 дней после создания пакета. Вы можете удалить пакет сообщений в любое время после обработки с помощью эндпоинта [`DELETE /v1/messages/batches/{batch_id}`](https://platform.claude.com/docs/ru/api/messages/batches/delete). Чтобы удалить пакет, находящийся в процессе обработки, сначала отмените его. Асинхронная обработка требует хранения как входных, так и выходных данных на стороне сервера до завершения пакета и получения результатов.

## Дальнейшие шаги

<CardGroup cols={2}>
  <Card title="Результаты поиска" icon="magnifying-glass" href="https://platform.claude.com/docs/ru/build-with-claude/search-results">
    Получайте естественные цитаты для приложений RAG, предоставляя результаты поиска с указанием источников.
  </Card>

  <Card title="Кэширование подсказок" icon="database" href="https://platform.claude.com/docs/ru/build-with-claude/prompt-caching">
    Снижайте затраты и задержку, кэшируя префиксы подсказок, общие для запросов в пакете.
  </Card>
</CardGroup>
