---
title: Elaborazione batch
url: https://platform.claude.com/docs/it/build-with-claude/batch-processing
description: Elabora grandi volumi di richieste Messages in modo asincrono con la Message Batches API, riducendo i costi del 50% e aumentando il throughput.
---

L'elaborazione batch ("batch processing") è un approccio potente per gestire grandi volumi di richieste in modo efficiente. Invece di elaborare le richieste una alla volta con risposte immediate, l'elaborazione batch ti consente di inviare più richieste insieme per l'elaborazione asincrona. Questo pattern è particolarmente utile quando:

* Devi elaborare grandi volumi di dati
* Non sono necessarie risposte immediate
* Vuoi ottimizzare l'efficienza dei costi
* Stai eseguendo valutazioni o analisi su larga scala

La Message Batches API è la prima implementazione di questo pattern da parte di Anthropic.

<Note>
  Per scoprire come la "zero data retention" (conservazione zero dei dati), o ZDR, si applica a questa funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).
</Note>

# Message Batches API

La Message Batches API è un modo potente ed economico per elaborare in modo asincrono grandi volumi di richieste [Messages](https://platform.claude.com/docs/it/api/messages/create). Questo approccio è adatto ad attività che non richiedono risposte immediate: la maggior parte dei batch termina in meno di 1 ora, riducendo i costi del 50% e aumentando il throughput.

Puoi [esplorare direttamente il riferimento API](https://platform.claude.com/docs/it/api/messages/batches/create), oltre a questa guida.

## Come funziona la Message Batches API

Quando invii una richiesta alla Message Batches API:

1. Il sistema crea un nuovo Message Batch con le richieste Messages fornite.
2. Il batch viene quindi elaborato in modo asincrono, con ogni richiesta gestita in modo indipendente.
3. Puoi interrogare lo stato del batch e recuperare i risultati quando l'elaborazione è terminata per tutte le richieste.

Questo è particolarmente utile per operazioni in blocco che non richiedono risultati immediati, come:

* Valutazioni su larga scala: elabora migliaia di casi di test in modo efficiente.
* Moderazione dei contenuti: analizza grandi volumi di contenuti generati dagli utenti in modo asincrono.
* Analisi dei dati: genera approfondimenti o riepiloghi per grandi dataset.
* Generazione di contenuti in blocco: crea grandi quantità di testo per vari scopi (ad esempio, descrizioni di prodotti, riepiloghi di articoli).

### Limitazioni dei batch

* Un Message Batch è limitato a 100.000 richieste Message oppure a 256 MB di dimensione, a seconda di quale limite viene raggiunto per primo.
* Il sistema elabora ogni batch il più velocemente possibile, con la maggior parte dei batch completati entro 1 ora. Puoi accedere ai risultati del batch quando tutti i messaggi sono stati completati o dopo 24 ore, a seconda di quale condizione si verifica per prima. I batch scadono se l'elaborazione non viene completata entro 24 ore.
* I risultati dei batch sono disponibili per 29 giorni dopo la creazione. Dopo tale periodo, puoi ancora visualizzare il Batch, ma i suoi risultati non saranno più disponibili per il download.
* I batch sono limitati all'ambito di un [Workspace](https://platform.claude.com/settings/workspaces). Puoi visualizzare tutti i batch (e i relativi risultati) creati all'interno del Workspace in cui viene eseguita la tua richiesta.
* I "rate limits" (limiti di velocità) si applicano sia alle richieste HTTP della Batches API sia al numero di richieste all'interno di un batch in attesa di elaborazione. Consulta [Limiti di velocità della Message Batches API](https://platform.claude.com/docs/it/api/rate-limits#message-batches-api). Inoltre, l'elaborazione potrebbe essere rallentata in base alla domanda corrente e al volume delle tue richieste. In tal caso, potresti vedere più richieste scadere dopo 24 ore.
* A causa dell'elevato throughput e dell'elaborazione concorrente, i batch potrebbero superare leggermente il [limite di spesa](https://platform.claude.com/settings/billing) configurato per il tuo Workspace.
* Ogni richiesta in batch deve avere `max_tokens` pari ad almeno `1`. `max_tokens: 0` ([pre-riscaldamento della cache](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#pre-warming-the-cache)) non è supportato all'interno di un batch, perché una voce di cache effimera scritta durante l'elaborazione del batch probabilmente scadrebbe prima dell'esecuzione della richiesta successiva.

### Modelli supportati

Tutti i [modelli attivi](https://platform.claude.com/docs/it/models/overview) supportano la Message Batches API.

### Cosa può essere inserito in un batch

Quasi tutte le richieste che puoi effettuare alla Messages API possono essere incluse in un batch. Questo include:

* Visione
* "Tool use" (uso degli strumenti), inclusi tutti gli [strumenti server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools) (web search, web fetch, code execution, connettori MCP, advisor e tool search)
* Messaggi di sistema
* Conversazioni multi-turno
* "Extended thinking" (ragionamento esteso)
* La maggior parte delle funzionalità beta

Poiché ogni richiesta nel batch viene elaborata in modo indipendente, puoi combinare diversi tipi di richieste all'interno di un singolo batch.

Un piccolo numero di parametri della Messages API **non** è supportato nelle richieste batch. L'inclusione di uno qualsiasi di questi restituisce un errore di validazione:

| Parametro                                                                                    | Motivo                                                                                                                      |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `stream: true`                                                                               | I risultati del batch vengono restituiti come un singolo file, non come uno stream.                                         |
| `speed` ([Modalità veloce](https://platform.claude.com/docs/it/build-with-claude/fast-mode)) | La modalità veloce ottimizza la "latency" (latenza) sincrona, che non si applica all'elaborazione batch asincrona.          |
| `max_tokens: 0`                                                                              | Consulta [Limitazioni dei batch](https://platform.claude.com/docs/it/build-with-claude/batch-processing#batch-limitations). |

<Tip>
  Poiché l'elaborazione dei batch può richiedere più di 5 minuti, considera l'utilizzo della [durata della cache di 1 ora](https://platform.claude.com/docs/it/build-with-claude/prompt-caching#1-hour-cache-duration) con la cache dei prompt per ottenere tassi di cache hit migliori quando elabori batch con contesto condiviso.
</Tip>

## Prezzi

La Batches API offre risparmi significativi sui costi. Tutto l'utilizzo viene addebitato al 50% dei prezzi standard dell'API.

| Model                                                                                                                                | Batch input  | Batch output  |
| :----------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------ |
| 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 Bedrock and Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/it/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 Bedrock and Google Cloud](https://platform.claude.com/docs/it/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  |
| Claude Haiku 3.5 ([retired, except on Google Cloud](https://platform.claude.com/docs/it/about-claude/model-deprecations))            | $0.40 / MTok | $2 / 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/it/about-claude/model-deprecations) for more.

## Come usare la Message Batches API

### Prepara e crea il tuo batch

Un Message Batch è composto da un elenco di richieste per creare un Message. La forma di una singola richiesta comprende:

* Un `custom_id` univoco per identificare la richiesta Messages. Deve essere compreso tra 1 e 64 caratteri e contenere solo caratteri alfanumerici, trattini e underscore (corrispondente a `^[a-zA-Z0-9_-]{1,64}$`).
* Un oggetto `params` con i parametri standard della [Messages API](https://platform.claude.com/docs/it/api/messages/create)

Puoi [creare un batch](https://platform.claude.com/docs/it/api/messages/batches/create) passando questo elenco nel parametro `requests`:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages/batches \
       --header "x-api-key: $ANTHROPIC_API_KEY" \
       --header "anthropic-version: 2023-06-01" \
       --header "content-type: application/json" \
       --data \
  '{
      "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() { Role = Role.User, Content = "Hello, world" }
                  ]
              }
          },
          new()
          {
              CustomID = "my-second-request",
              Params = new()
              {
                  Model = Model.ClaudeOpus5_5,
                  MaxTokens = 1024,
                  Messages =
                  [
                      new() { Role = Role.User, 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: "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" }
          ]
        }
      }
    ]
  )

  puts batch
  ```
</CodeGroup>

In questo esempio, due richieste separate vengono raggruppate in un batch per l'elaborazione asincrona. Ogni richiesta ha un `custom_id` univoco e contiene i parametri standard che useresti per una chiamata alla Messages API.

<Tip>
  **Testa le tue richieste batch con la Messages API**

  La validazione dell'oggetto `params` per ogni richiesta di messaggio viene eseguita in modo asincrono e gli errori di validazione vengono restituiti quando l'elaborazione dell'intero batch è terminata. Puoi assicurarti di costruire correttamente il tuo input verificando prima la forma della tua richiesta con la [Messages API](https://platform.claude.com/docs/it/api/messages/create).
</Tip>

Quando un batch viene creato per la prima volta, la risposta ha uno stato di elaborazione `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
}
```

### Monitoraggio del tuo batch

Il campo `processing_status` del Message Batch indica la fase di elaborazione in cui si trova il batch. Inizia come `in_progress`, poi si aggiorna a `ended` una volta che tutte le richieste nel batch hanno terminato l'elaborazione e i risultati sono pronti. Puoi monitorare lo stato del tuo batch visitando la [Console](https://platform.claude.com/settings/workspaces/default/batches) o utilizzando l'[endpoint di recupero](https://platform.claude.com/docs/it/api/messages/batches/retrieve).

#### Polling per il completamento del Message Batch

Per effettuare il polling di un Message Batch, avrai bisogno del suo `id`, che viene fornito nella risposta alla creazione di un batch o elencando i batch. Puoi implementare un ciclo di polling che controlla periodicamente lo stato del batch finché l'elaborazione non è terminata:

<CodeGroup>
  ```bash cURL
  #!/bin/sh
  # ...
  # Controlla lo stato; ripeti finché processing_status non è "ended"
  curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    | jq -r '.processing_status'
  ```

  ```bash CLI
  #!/bin/bash
  # ...
  # Controlla lo stato; ripeti finché processing_status non è "ended"
  ant messages:batches retrieve \
    --message-batch-id "$MESSAGE_BATCH_ID" \
    --transform processing_status --raw-output
  ```

  ```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>

### Elencare tutti i Message Batches

Puoi elencare tutti i Message Batches nel tuo Workspace utilizzando l'[endpoint di elenco](https://platform.claude.com/docs/it/api/messages/batches/list). L'API supporta la paginazione, recuperando automaticamente pagine aggiuntive secondo necessità:

<CodeGroup>
  ```bash cURL
  #!/bin/sh
  # Recupera una pagina. Finché has_more della risposta è true, passa il suo
  # last_id come after_id per recuperare la pagina successiva. (Gli SDK e la CLI
  # eseguono la paginazione automatica.)
  curl -s "https://api.anthropic.com/v1/messages/batches?limit=20" \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01"
  ```

  ```bash CLI
  # Recupera automaticamente altre pagine secondo necessità
  ant messages:batches list --limit 20
  ```

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

  # Recupera automaticamente altre pagine secondo necessità.
  for message_batch in client.messages.batches.list(limit=20):
      print(message_batch)
  ```

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

  // Recupera automaticamente altre pagine secondo necessità.
  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
  };

  // Recupera automaticamente altre pagine secondo necessità
  var page = await client.Messages.Batches.List(parameters);
  await foreach (var messageBatch in page.Paginate())
  {
      Console.WriteLine(messageBatch);
  }
  ```

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

  // Recupera automaticamente altre pagine secondo necessità
  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();

  // Recupera automaticamente altre pagine secondo necessità
  for (MessageBatch messageBatch : client
    .messages()
    .batches()
    .list(BatchListParams.builder().limit(20).build())
    .autoPager()) {
    System.out.println(messageBatch);
  }
  ```

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

  // Recupera automaticamente altre pagine secondo necessità
  foreach ($client->messages->batches->list(limit: 20)->pagingEachItem() as $messageBatch) {
      echo $messageBatch->id . "\n";
  }
  ```

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

  # Recupera automaticamente altre pagine secondo necessità
  client.messages.batches.list(limit: 20).auto_paging_each do |message_batch|
    puts message_batch
  end
  ```
</CodeGroup>

### Recupero dei risultati del batch

Una volta terminata l'elaborazione del batch, ogni richiesta Messages nel batch ha un risultato. Esistono quattro tipi di risultato:

| Tipo di risultato | Descrizione                                                                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `succeeded`       | La richiesta è andata a buon fine. Include il risultato del messaggio.                                                                                                                                |
| `errored`         | La richiesta ha riscontrato un errore e non è stato creato un messaggio. I possibili errori includono richieste non valide ed errori interni del server. Queste richieste non ti verranno addebitate. |
| `canceled`        | L'utente ha annullato il batch prima che questa richiesta potesse essere inviata al modello. Queste richieste non ti verranno addebitate.                                                             |
| `expired`         | Il batch ha raggiunto la scadenza di 24 ore prima che questa richiesta potesse essere inviata al modello. Queste richieste non ti verranno addebitate.                                                |

Il campo `request_counts` del batch mostra una panoramica dei tuoi risultati, indicando quante richieste hanno raggiunto ciascuno di questi quattro stati.

I risultati del batch sono disponibili per il download alla proprietà `results_url` del Message Batch e, se l'autorizzazione dell'organizzazione lo consente, nella Console. A causa delle dimensioni potenzialmente elevate dei risultati, si consiglia di recuperare i [risultati in streaming](https://platform.claude.com/docs/it/api/messages/batches/results) anziché scaricarli tutti in una volta.

<CodeGroup>
  ```bash cURL
  #!/bin/sh
  # Recupera il results_url del batch, poi esegui lo streaming dei risultati .jsonl
  # a cui punta. Per la gestione per singolo risultato (retry, errori di validazione),
  # usa gli esempi SDK nelle altre schede.
  RESULTS_URL=$(curl -s "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
    --header "anthropic-version: 2023-06-01" \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    | jq -r '.results_url')

  curl -s "$RESULTS_URL" \
    --header "anthropic-version: 2023-06-01" \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    | jq -r '"\(.result.type): \(.custom_id)"'
  ```

  ```bash CLI
  # Stampa una riga per risultato, ad es. `{"custom_id":"test-1","type":"succeeded",…}`.
  # Per la gestione per singolo risultato (nuovi tentativi, errori di validazione), usa gli esempi
  # dell'SDK nelle altre schede.
  ant messages:batches results \
    --message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
    --transform '{custom_id,"type":result.type,"error":result.error.error.type}' \
    --format jsonl
  ```

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

  # Esegui lo streaming del file dei risultati in blocchi a basso consumo di memoria, elaborandone uno alla volta
  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":
                  # Il corpo della richiesta deve essere corretto prima di inviare di nuovo la richiesta
                  print(f"Validation error {result.custom_id}")
              else:
                  # La richiesta può essere ritentata direttamente
                  print(f"Server error {result.custom_id}")
          case "expired":
              print(f"Request expired {result.custom_id}")
  ```

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

  // Trasmetti in streaming il file dei risultati in blocchi efficienti in memoria, elaborandoli uno alla volta
  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.type === "invalid_request_error") {
          // Il corpo della richiesta deve essere corretto prima di inviarla di nuovo
          console.log(`Validation error: ${result.custom_id}`);
        } else {
          // La richiesta può essere ritentata direttamente
          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)
      {
          case "succeeded":
              Console.WriteLine($"Success! {result.CustomID}");
              break;
          case "errored":
              if (result.Result.Error?.Type == "invalid_request")
              {
                  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();

      // Esegui lo streaming del file dei risultati in blocchi efficienti in memoria, elaborandone uno alla volta
      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()) {
                  // Il corpo della richiesta deve essere corretto prima di inviare di nuovo la richiesta
                  System.out.println("Validation error: " + result.customId());
                } else {
                  // La richiesta può essere ritentata direttamente
                  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.type == :invalid_request
        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>

I risultati sono in formato `.jsonl`, dove ogni riga è un oggetto JSON valido che rappresenta il risultato di una singola richiesta nel Message Batch. Per ogni risultato in streaming, puoi fare qualcosa di diverso a seconda del suo `custom_id` e del tipo di risultato. Ecco un esempio di insieme di risultati:

```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}}}}
```

Se il tuo risultato contiene un errore, il suo `result.error` sarà impostato sulla [forma di errore](https://platform.claude.com/docs/it/api/errors#error-shapes) standard.

<Tip>
  **I risultati del batch potrebbero non corrispondere all'ordine di input**

  I risultati del batch possono essere restituiti in qualsiasi ordine e potrebbero non corrispondere all'ordine delle richieste al momento della creazione del batch. Nell'esempio precedente, il risultato della seconda richiesta del batch viene restituito prima della prima. Per abbinare correttamente i risultati alle richieste corrispondenti, usa sempre il campo `custom_id`.
</Tip>

### Annullamento di un Message Batch

Puoi annullare un Message Batch attualmente in elaborazione utilizzando l'[endpoint di annullamento](https://platform.claude.com/docs/it/api/messages/batches/cancel). Immediatamente dopo l'annullamento, il `processing_status` di un batch sarà `canceling`. Puoi usare la stessa tecnica di polling descritta in precedenza per attendere che l'annullamento sia finalizzato. I batch annullati terminano con uno stato `ended` e possono contenere risultati parziali per le richieste elaborate prima dell'annullamento.

<CodeGroup>
  ```bash cURL
  #!/bin/sh
  # ...
  curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      --header "anthropic-version: 2023-06-01"
  ```

  ```bash CLI
  #!/bin/bash
  # ...
  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>

La risposta mostra il batch in stato `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
}
```

### Uso della cache dei prompt con i Message Batches

La Message Batches API supporta il "prompt caching" (cache dei prompt), consentendoti potenzialmente di ridurre i costi e i tempi di elaborazione per le richieste batch. Gli sconti sui prezzi derivanti dalla cache dei prompt e dai Message Batches possono cumularsi, offrendo risparmi ancora maggiori quando entrambe le funzionalità vengono utilizzate insieme. Tuttavia, poiché le richieste batch vengono elaborate in modo asincrono e concorrente, i cache hit vengono forniti secondo il principio del best-effort. Gli utenti in genere riscontrano tassi di cache hit compresi tra il 30% e il 98%, a seconda dei loro pattern di traffico.

Per massimizzare la probabilità di cache hit nelle tue richieste batch:

1. Includi blocchi `cache_control` identici in ogni richiesta Message all'interno del tuo batch.
2. Mantieni un flusso costante di richieste per evitare che le voci della cache scadano dopo la loro durata di 5 minuti.
3. Struttura le tue richieste in modo da condividere quanto più contenuto in cache possibile.

Esempio di implementazione della cache dei prompt in un batch:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages/batches \
       --header "x-api-key: $ANTHROPIC_API_KEY" \
       --header "anthropic-version: 2023-06-01" \
       --header "content-type: application/json" \
       --data \
  '{
      "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() { Role = Role.User, 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() { Role = Role.User, 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: "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." }
          ]
        }
      }
    ]
  )
  ```
</CodeGroup>

In questo esempio, entrambe le richieste nel batch includono messaggi di sistema identici e il testo completo di Orgoglio e pregiudizio contrassegnato con `cache_control` per aumentare la probabilità di cache hit.

### Strumenti server e ciclo agentico

Tutti gli [strumenti server](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools) (web search, web fetch, code execution, connettori MCP, advisor e tool search) funzionano nelle richieste batch. Il worker batch esegue lo stesso ciclo agentico lato server della Messages API sincrona.

Poiché non c'è una connessione aperta da mantenere, il ciclo batch esegue **più iterazioni per turno** rispetto a una richiesta sincrona prima di restituire `stop_reason: "pause_turn"`. Se un risultato batch viene restituito con `pause_turn`, il turno non è terminato; puoi continuarlo inviando il contenuto dell'assistente in pausa in una richiesta successiva (batch o sincrona) esattamente come mostrato nel [pattern di continuazione pause\_turn](https://platform.claude.com/docs/it/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn).

Il worker batch limita inoltre `web_search` per organizzazione, in modo che l'elaborazione batch altamente concorrente non esaurisca il limite di velocità di web search della tua organizzazione. Il batch ritenta automaticamente le richieste limitate; non devi gestirlo tu stesso, ma batch di web search molto grandi potrebbero richiedere più tempo per essere completati.

### Output esteso (beta)

L'header beta `output-300k-2026-03-24` aumenta il limite di `max_tokens` a 300.000 per le richieste batch che usano 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 o Claude Haiku 5.5. Includi l'header per generare output molto più lunghi del limite standard di 128k `max_tokens` in un singolo turno.

<Note>
  L'output esteso è disponibile solo sulla Message Batches API, non sulla Messages API sincrona. È supportato sulla Claude API e su Claude Platform su AWS, e non è attualmente disponibile su Amazon Bedrock, Google Cloud o Microsoft Foundry.
</Note>

Usa l'output esteso per la generazione di contenuti lunghi come bozze della lunghezza di un libro e documentazione tecnica, estrazione esaustiva di dati strutturati, grandi scaffold di generazione di codice e lunghe catene di ragionamento.

Una singola generazione da 300k token può richiedere più di un'ora per essere completata, quindi pianifica l'invio dei tuoi batch tenendo presente la finestra di elaborazione di 24 ore. Si applicano i prezzi batch standard (50% dei prezzi standard dell'API).

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages/batches \
       --header "x-api-key: $ANTHROPIC_API_KEY" \
       --header "anthropic-version: 2023-06-01" \
       --header "anthropic-beta: output-300k-2026-03-24" \
       --header "content-type: application/json" \
       --data \
  '{
      "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() { Role = Role.User, 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: "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>

### Best practice per un batching efficace

Per ottenere il massimo dalla Batches API:

* Monitora regolarmente lo stato di elaborazione dei batch e implementa una logica di retry appropriata per le richieste non riuscite.
* Usa valori `custom_id` significativi per abbinare facilmente i risultati alle richieste, poiché l'ordine non è garantito.
* Considera di suddividere dataset molto grandi in più batch per una migliore gestibilità.
* Esegui una prova a secco di una singola forma di richiesta con la Messages API per evitare errori di validazione.

### Risoluzione dei problemi comuni

Se riscontri un comportamento inatteso:

* Verifica che la dimensione totale della richiesta batch non superi 256 MB. Se la dimensione della richiesta è troppo grande, potresti ricevere un errore 413 `request_too_large`.
* Controlla di utilizzare [modelli supportati](https://platform.claude.com/docs/it/build-with-claude/batch-processing#supported-models) per tutte le richieste nel batch.
* Assicurati che ogni richiesta nel batch abbia un `custom_id` univoco.
* Assicurati che siano trascorsi meno di 29 giorni dal momento `created_at` del batch (non dal momento `ended_at` dell'elaborazione). Se sono trascorsi più di 29 giorni, i risultati non saranno più visualizzabili.
* Conferma che il batch non sia stato annullato.

Nota che il fallimento di una richiesta in un batch non influisce sull'elaborazione delle altre richieste.

## Archiviazione dei batch e privacy

* **Isolamento del Workspace**: i batch sono isolati all'interno del Workspace in cui vengono creati. Possono essere accessibili solo tramite richieste API nello stesso Workspace o da utenti con l'autorizzazione a visualizzare i batch del Workspace nella Console.

* **Disponibilità dei risultati**: i risultati dei batch sono disponibili per 29 giorni dopo la creazione del batch, consentendo ampio tempo per il recupero e l'elaborazione.

## Conservazione dei dati

L'elaborazione batch archivia i dati di richiesta e risposta per un massimo di 29 giorni dopo la creazione del batch. Puoi eliminare un message batch in qualsiasi momento dopo l'elaborazione utilizzando l'endpoint `DELETE /v1/messages/batches/{batch_id}`. Per eliminare un batch in corso, annullalo prima. L'elaborazione asincrona richiede l'archiviazione lato server sia degli input che degli output fino al completamento del batch e al recupero dei risultati.

Per l'idoneità ZDR di tutte le funzionalità, consulta [API e conservazione dei dati](https://platform.claude.com/docs/it/manage-claude/api-and-data-retention).

## Domande frequenti

<AccordionGroup>
  <Accordion title="Quanto tempo richiede l'elaborazione di un batch?">
    I batch possono richiedere fino a 24 ore per l'elaborazione, ma molti terminano prima. Il tempo di elaborazione effettivo dipende dalla dimensione del batch, dalla domanda corrente e dal volume delle tue richieste. È possibile che un batch scada e non venga completato entro 24 ore.
  </Accordion>

  <Accordion title="La Batches API è disponibile per tutti i modelli?">
    Consulta [Modelli supportati](https://platform.claude.com/docs/it/build-with-claude/batch-processing#supported-models) per l'elenco dei modelli supportati.
  </Accordion>

  <Accordion title="Posso usare la Message Batches API con altre funzionalità dell'API?">
    Sì, la Message Batches API supporta quasi tutte le funzionalità disponibili nella Messages API, inclusa la maggior parte delle funzionalità beta. Un piccolo numero di parametri (`stream`, `speed` e `max_tokens: 0`) non è supportato. Consulta [Cosa può essere inserito in un batch](https://platform.claude.com/docs/it/build-with-claude/batch-processing#what-can-be-batched) per l'elenco completo.
  </Accordion>

  <Accordion title="In che modo la Message Batches API influisce sui prezzi?">
    La Message Batches API offre uno sconto del 50% su tutto l'utilizzo rispetto ai prezzi standard dell'API. Questo si applica ai token di input, ai token di output e a qualsiasi token speciale. Per maggiori informazioni sui prezzi, visita [Prezzi](https://claude.com/pricing#anthropic-api).
  </Accordion>

  <Accordion title="Posso aggiornare un batch dopo che è stato inviato?">
    No, una volta che un batch è stato inviato, non può essere modificato. Se devi apportare modifiche, dovresti annullare il batch corrente e inviarne uno nuovo. Nota che l'annullamento potrebbe non avere effetto immediato.
  </Accordion>

  <Accordion title="Esistono limiti di velocità per la Message Batches API e interagiscono con i limiti di velocità della Messages API?">
    La Message Batches API ha limiti di velocità basati sulle richieste HTTP oltre a limiti sul numero di richieste in attesa di elaborazione. Consulta [Limiti di velocità della Message Batches API](https://platform.claude.com/docs/it/api/rate-limits#message-batches-api). L'utilizzo della Batches API non influisce sui limiti di velocità della Messages API.
  </Accordion>

  <Accordion title="Come gestisco gli errori nelle mie richieste batch?">
    Quando recuperi i risultati, ogni richiesta ha un campo `result` che indica se è `succeeded`, `errored`, `canceled` o `expired`. Per i risultati `errored`, vengono fornite informazioni aggiuntive sull'errore. Visualizza l'oggetto di risposta di errore nel [riferimento API](https://platform.claude.com/docs/it/api/messages/batches/create).
  </Accordion>

  <Accordion title="In che modo la Message Batches API gestisce la privacy e la separazione dei dati?">
    La Message Batches API è progettata con solide misure di privacy e separazione dei dati:

    1. I batch e i relativi risultati sono isolati all'interno del Workspace in cui sono stati creati. Ciò significa che possono essere accessibili solo tramite richieste API nello stesso Workspace.
    2. Ogni richiesta all'interno di un batch viene elaborata in modo indipendente, senza fughe di dati tra le richieste.
    3. I risultati sono disponibili solo per un periodo limitato (29 giorni) e seguono la [politica di conservazione dei dati](https://support.claude.com/en/articles/7996866-how-long-do-you-store-personal-data) di Anthropic.
    4. Il download dei risultati dei batch nella Console può essere disabilitato a livello di organizzazione o per singolo workspace.
  </Accordion>

  <Accordion title="Posso usare la cache dei prompt nella Message Batches API?">
    Sì, è possibile usare la cache dei prompt con la Message Batches API. Tuttavia, poiché le richieste batch asincrone possono essere elaborate in modo concorrente e in qualsiasi ordine, i cache hit vengono forniti secondo il principio del best-effort.
  </Accordion>
</AccordionGroup>

## Prossimi passi

<CardGroup cols={2}>
  <Card title="Risultati di ricerca" icon="magnifying-glass" href="https://platform.claude.com/docs/it/build-with-claude/search-results">
    Abilita citazioni naturali per applicazioni RAG fornendo risultati di ricerca con attribuzione della fonte.
  </Card>

  <Card title="Cache dei prompt" icon="database" href="https://platform.claude.com/docs/it/build-with-claude/prompt-caching">
    Riduci costi e latenza memorizzando nella cache i prefissi dei prompt condivisi tra le richieste di un batch.
  </Card>
</CardGroup>