---
title: Traitement par lots
url: https://platform.claude.com/docs/fr/build-with-claude/batch-processing
description: Traitez de grands volumes de requêtes Messages de manière asynchrone avec l'API Message Batches, en réduisant les coûts de 50 pour cent et en augmentant le débit.
featureMetadata:
status: stable
zdr:
eligibility: not-eligible
note: Conservation de 29 jours ; stockage asynchrone requis.
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
---
Le « batch processing » (traitement par lots) est une approche puissante pour gérer efficacement de grands volumes de requêtes. Au lieu de traiter les requêtes une par une avec des réponses immédiates, le traitement par lots vous permet de soumettre plusieurs requêtes ensemble pour un traitement asynchrone. Ce modèle est particulièrement utile lorsque :
* Vous devez traiter de grands volumes de données.
* Des réponses immédiates ne sont pas nécessaires.
* Vous souhaitez optimiser la rentabilité.
* Vous exécutez des évaluations ou des analyses à grande échelle.
L’API Message Batches est la première implémentation de ce modèle par Anthropic.
# API Message Batches
L’API Message Batches est un moyen puissant et économique de traiter de manière asynchrone de grands volumes de requêtes [Messages](https://platform.claude.com/docs/fr/api/messages/create). Cette approche est bien adaptée aux tâches qui ne nécessitent pas de réponses immédiates, la plupart des lots se terminant en moins d’une heure tout en réduisant les coûts de 50 pour cent et en augmentant le débit.
Vous pouvez [explorer directement la référence de l’API](https://platform.claude.com/docs/fr/api/messages/batches/create), en plus de ce guide.
## Fonctionnement de l’API Message Batches
Lorsque vous envoyez une requête à l’API Message Batches :
1. Le système crée un nouveau lot de messages avec les requêtes Messages fournies.
2. Le lot est ensuite traité de manière asynchrone, chaque requête étant traitée indépendamment.
3. Vous pouvez interroger le statut du lot et récupérer les résultats lorsque le traitement est terminé pour toutes les requêtes.
Ceci est particulièrement utile pour les opérations en masse qui ne nécessitent pas de résultats immédiats, telles que :
* Évaluations à grande échelle : traitez efficacement des milliers de cas de test.
* Modération de contenu : analysez de manière asynchrone de grands volumes de contenu généré par les utilisateurs.
* Analyse de données : générez des informations ou des résumés pour de grands ensembles de données.
* Génération de contenu en masse : créez de grandes quantités de texte à des fins diverses (par exemple, descriptions de produits, résumés d’articles).
### Limitations des lots
* Un lot de messages est limité à 100 000 requêtes Message ou à 256 Mo de taille, selon la limite atteinte en premier.
* Le système traite chaque lot aussi rapidement que possible, la plupart des lots se terminant en moins d’une heure. Vous pouvez accéder aux résultats du lot lorsque tous les messages sont terminés ou après 24 heures, selon ce qui survient en premier. Les lots expirent si le traitement ne se termine pas dans les 24 heures.
* Les résultats des lots sont disponibles pendant 29 jours après leur création. Passé ce délai, vous pouvez toujours consulter le lot, mais ses résultats ne seront plus disponibles au téléchargement.
* Les lots sont limités à un [espace de travail](https://platform.claude.com/settings/workspaces) dans la Claude Console. Vous pouvez consulter tous les lots (et leurs résultats) qui ont été créés dans l’espace de travail dans lequel votre requête s’exécute.
* Les limites de débit s’appliquent à la fois aux requêtes HTTP de l’API Batches et au nombre de requêtes d’un lot en attente de traitement. Consultez [Limites de débit de l’API Message Batches](https://platform.claude.com/docs/fr/api/rate-limits#message-batches-api). De plus, le traitement peut être ralenti en fonction de la demande actuelle et de votre volume de requêtes. Dans ce cas, vous pourriez voir davantage de requêtes expirer après 24 heures.
* En raison du débit élevé et du traitement simultané, les lots peuvent légèrement dépasser la [limite de dépenses](https://platform.claude.com/settings/billing) configurée dans la Claude Console pour votre espace de travail.
* Chaque requête d’un lot doit avoir un [`max_tokens`](https://platform.claude.com/docs/fr/api/messages/create#create.max_tokens) d’au moins `1`. `max_tokens: 0` ([préchauffage du cache](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#pre-warming-the-cache)) n’est pas pris en charge dans un lot, car une entrée de cache éphémère écrite pendant le traitement du lot expirerait probablement avant l’exécution de la requête suivante.
### Modèles pris en charge
Tous les [modèles actifs](https://platform.claude.com/docs/fr/models/overview) prennent en charge l’API Message Batches.
### Ce qui peut être traité par lots
Presque toutes les requêtes que vous pouvez adresser à l’API Messages peuvent être incluses dans un lot. Cela inclut :
* La vision
* L’utilisation d’outils, y compris tous les [outils serveur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/server-tools) (recherche web, récupération web, exécution de code, connecteurs MCP, conseiller et recherche d’outils)
* Les messages système
* Les conversations multi-tours
* La réflexion étendue
* La plupart des fonctionnalités bêta
Étant donné que chaque requête du lot est traitée indépendamment, vous pouvez mélanger différents types de requêtes au sein d’un même lot.
Un petit nombre de paramètres de l’API Messages ne sont **pas** pris en charge dans les requêtes par lots. L’inclusion de l’un d’entre eux renvoie une erreur de validation :
| Paramètre | Raison |
| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stream: true` | Les résultats des lots sont renvoyés sous forme d’un fichier unique, et non d’un flux. |
| `speed` ([Mode rapide](https://platform.claude.com/docs/fr/build-with-claude/fast-mode)) | Le mode rapide optimise la latence synchrone, ce qui ne s’applique pas au traitement asynchrone par lots. |
| `fallbacks` ([Repli côté serveur](https://platform.claude.com/docs/fr/build-with-claude/refusals-and-fallback#server-side-fallback)) | Le repli côté serveur ne s’applique pas aux lots. Pour réessayer les requêtes refusées, consultez [Refus dans les Message Batches](https://platform.claude.com/docs/fr/build-with-claude/refusals-and-fallback#refusals-in-message-batches). |
| `max_tokens: 0` | Consultez [Limitations des lots](https://platform.claude.com/docs/fr/build-with-claude/batch-processing#batch-limitations). |
Étant donné que le traitement des lots peut prendre plus de 5 minutes, envisagez d’utiliser la [durée de cache d’une heure](https://platform.claude.com/docs/fr/build-with-claude/prompt-caching#1-hour-cache-duration) avec la mise en cache des prompts pour obtenir de meilleurs taux de succès du cache lors du traitement de lots partageant un contexte commun.
## Tarification
L’API Batches offre des économies significatives. Toute l’utilisation est facturée à 50 pour cent des prix standard de l’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/fr/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/fr/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/fr/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/fr/about-claude/model-deprecations) for more.
## Comment utiliser l’API Message Batches
### Préparer et créer votre lot
Un lot de messages est composé d’une liste de requêtes de création d’un Message. La structure d’une requête individuelle comprend :
* Un [`custom_id`](https://platform.claude.com/docs/fr/api/messages/batches/create#create.requests.custom_id) unique pour identifier la requête Messages. Il doit comporter de 1 à 64 caractères et ne contenir que des caractères alphanumériques, des traits d’union et des traits de soulignement (correspondant à `^[a-zA-Z0-9_-]{1,64}$`).
* Un objet [`params`](https://platform.claude.com/docs/fr/api/messages/batches/create#create.requests.params) avec les paramètres standard de l’[API Messages](https://platform.claude.com/docs/fr/api/messages/create).
Vous pouvez [créer un lot](https://platform.claude.com/docs/fr/api/messages/batches/create) en passant cette liste dans le paramètre `requests` :
```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
```
Dans cet exemple, deux requêtes distinctes sont regroupées pour un traitement asynchrone. Chaque requête possède un `custom_id` unique et contient les paramètres standard que vous utiliseriez pour un appel à l’API Messages.
**Testez vos requêtes par lots avec l’API Messages**
La validation de l’objet `params` pour chaque requête de message est effectuée de manière asynchrone, et les erreurs de validation sont renvoyées lorsque le traitement de l’ensemble du lot est terminé. Vous pouvez vous assurer que vous construisez correctement vos entrées en vérifiant d’abord la structure de votre requête avec l’[API Messages](https://platform.claude.com/docs/fr/api/messages/create).
Lorsqu’un lot est créé pour la première fois, la réponse a un statut de traitement `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
}
```
### Suivre votre lot
Le champ [`processing_status`](https://platform.claude.com/docs/fr/api/messages/batches/retrieve#message_batch.processing_status) du lot de messages indique l’étape de traitement dans laquelle se trouve le lot. Il commence à `in_progress`, puis passe à `ended` une fois que toutes les requêtes du lot ont fini d’être traitées et que les résultats sont prêts. Vous pouvez surveiller l’état de votre lot en visitant la [Console](https://platform.claude.com/settings/workspaces/default/batches), ou en utilisant le point de terminaison de récupération.
(See the `messages/batches/retrieve` method in [the API reference](https://platform.claude.com/docs/fr/api/messages/batches/retrieve).)
#### Interroger l’achèvement d’un lot de messages
Pour interroger un lot de messages, vous aurez besoin de son `id`, qui est fourni dans la réponse lors de la création d’un lot ou en listant les lots. Vous pouvez implémenter une boucle d’interrogation qui vérifie périodiquement le statut du lot jusqu’à la fin du traitement :
```bash cURL
# Vérifiez le statut ; répétez jusqu'à ce que processing_status soit "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
# Vérifiez le statut ; répétez jusqu'à ce que processing_status soit "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
```
### Lister tous les lots de messages
Vous pouvez lister tous les lots de messages de votre espace de travail en utilisant le [point de terminaison de liste](https://platform.claude.com/docs/fr/api/messages/batches/list). L’API prend en charge la pagination, en récupérant automatiquement des pages supplémentaires si nécessaire :
```bash cURL
# Récupère une page. Tant que le champ has_more de la réponse est vrai, passez son
# last_id comme after_id pour récupérer la page suivante. (Les SDK et la CLI
# effectuent la pagination automatiquement.)
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
# Récupère automatiquement des pages supplémentaires si nécessaire.
ant messages:batches list --limit 20
```
```python Python
client = anthropic.Anthropic()
# Récupère automatiquement d'autres pages si nécessaire.
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
// Récupère automatiquement des pages supplémentaires si nécessaire.
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
};
// Récupère automatiquement des pages supplémentaires si nécessaire.
var page = await client.Messages.Batches.List(parameters);
await foreach (var messageBatch in page.Paginate())
{
Console.WriteLine(messageBatch);
}
```
```go Go
client := anthropic.NewClient()
// Récupère automatiquement des pages supplémentaires selon les besoins.
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();
// Récupère automatiquement d'autres pages si nécessaire.
for (MessageBatch messageBatch : client
.messages()
.batches()
.list(BatchListParams.builder()
.limit(20)
.build())
.autoPager()) {
System.out.println(messageBatch);
}
```
```php PHP
$client = new Client();
// Récupère automatiquement les pages suivantes si nécessaire.
foreach ($client->messages->batches->list(limit: 20)->pagingEachItem() as $messageBatch) {
echo $messageBatch->id . "\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
# Récupère automatiquement des pages supplémentaires si nécessaire.
client.messages.batches.list(limit: 20).auto_paging_each do |message_batch|
puts message_batch
end
```
### Récupérer les résultats d’un lot
Une fois le traitement du lot terminé, chaque requête Messages du lot a un résultat. Il existe quatre types de résultats :
| Type de résultat | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `succeeded` | La requête a réussi. Inclut le résultat du message. |
| `errored` | La requête a rencontré une erreur et aucun message n’a été créé. Les erreurs possibles incluent des requêtes invalides et des erreurs internes du serveur. Ces requêtes ne vous seront pas facturées. |
| `canceled` | L’utilisateur a annulé le lot avant que cette requête puisse être envoyée au modèle. Ces requêtes ne vous seront pas facturées. |
| `expired` | Le lot a atteint son expiration de 24 heures avant que cette requête puisse être envoyée au modèle. Ces requêtes ne vous seront pas facturées. |
L’objet `request_counts` du lot compte les requêtes encore en cours de traitement et les requêtes de chaque type de résultat.
(See `message_batch.request_counts` on `messages/batches/retrieve` in [the API reference](https://platform.claude.com/docs/fr/api/messages/batches/retrieve#message_batch.request_counts).)
Les résultats du lot sont disponibles au téléchargement via la propriété [`results_url`](https://platform.claude.com/docs/fr/api/messages/batches/retrieve#message_batch.results_url) du lot de messages et, si les autorisations de l’organisation le permettent, dans la Console. En raison de la taille potentiellement importante des résultats, il est recommandé de [récupérer les résultats en streaming](https://platform.claude.com/docs/fr/api/messages/batches/results) plutôt que de les télécharger tous en une seule fois.
```bash cURL
# Diffuse en streaming les résultats .jsonl du lot, un résultat par ligne.
# Pour un traitement par résultat (nouvelles tentatives, erreurs de validation), utilisez le SDK Claude.
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
# Affiche un résultat par ligne, par exemple `{"custom_id":"test-1","result":{"type":"succeeded",…}}`.
# Pour un traitement par résultat (nouvelles tentatives, erreurs de validation), utilisez les
# exemples du Claude SDK dans les autres onglets.
ant messages:batches results \
--message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
--format jsonl
```
```python Python
client = anthropic.Anthropic()
# Lit le fichier de résultats en streaming par blocs économes en mémoire, traités un par un.
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":
# Le corps de la requête doit être corrigé avant de renvoyer la requête.
print(f"Validation error {result.custom_id}")
else:
# La requête peut être relancée directement.
print(f"Server error {result.custom_id}")
case "expired":
print(f"Request expired {result.custom_id}")
```
```typescript TypeScript
const client = new Anthropic();
// Lire le fichier de résultats en streaming par blocs économes en mémoire, traités un à la fois.
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") {
// Le corps de la requête doit être corrigé avant de renvoyer la requête.
console.log(`Validation error: ${result.custom_id}`);
} else {
// La requête peut être relancée directement.
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();
// Lit le fichier de résultats en streaming par blocs économes en mémoire, traités un à un.
try (
StreamResponse 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()) {
// Le corps de la requête doit être corrigé avant de renvoyer la requête.
System.out.println("Validation error: " + result.customId());
} else {
// La requête peut être relancée directement.
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
```
Les résultats sont au format `.jsonl`, où chaque ligne est un objet JSON valide représentant le résultat d’une seule requête du lot de messages. Pour chaque résultat reçu en streaming, vous pouvez effectuer une action différente en fonction de son `custom_id` et de son type de résultat. Voici un exemple d’ensemble de résultats :
```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}}}}
```
Si votre résultat comporte une erreur, son `result.error` sera défini selon la [structure d’erreur](https://platform.claude.com/docs/fr/api/errors#error-shapes) standard.
Les résultats des lots utilisent la version de l’API de la requête qui a créé le lot.
**Les résultats des lots peuvent ne pas correspondre à l’ordre des entrées**
Les résultats des lots peuvent être renvoyés dans n’importe quel ordre et peuvent ne pas correspondre à l’ordre des requêtes lors de la création du lot. Dans l’exemple précédent, le résultat de la deuxième requête du lot est renvoyé avant celui de la première. Pour associer correctement les résultats à leurs requêtes correspondantes, utilisez toujours le champ `custom_id`.
### Annuler un lot de messages
Vous pouvez annuler un lot de messages en cours de traitement en utilisant le [point de terminaison d’annulation](https://platform.claude.com/docs/fr/api/messages/batches/cancel). Immédiatement après l’annulation, le `processing_status` d’un lot sera `canceling`. Vous pouvez utiliser la même technique d’interrogation décrite précédemment pour attendre que l’annulation soit finalisée. Les lots annulés se terminent avec un statut `ended` et peuvent contenir des résultats partiels pour les requêtes qui ont été traitées avant l’annulation.
```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
```
La réponse montre le lot dans un état `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
}
```
### Utiliser la mise en cache des prompts avec les Message Batches
L’API Message Batches prend en charge la « prompt caching » (mise en cache des prompts), ce qui vous permet potentiellement de réduire les coûts et le temps de traitement des requêtes par lots. Les réductions tarifaires de la mise en cache des prompts et des Message Batches peuvent se cumuler, offrant des économies encore plus importantes lorsque les deux fonctionnalités sont utilisées ensemble. Cependant, étant donné que les requêtes par lots sont traitées de manière asynchrone et simultanée, les succès du cache sont fournis dans la mesure du possible. Les utilisateurs constatent généralement des taux de succès du cache allant de 30 pour cent à 98 pour cent, selon leurs modèles de trafic.
Pour maximiser la probabilité de succès du cache dans vos requêtes par lots :
1. Incluez des blocs `cache_control` identiques dans chaque requête Message de votre lot.
2. Maintenez un flux régulier de requêtes pour éviter que les entrées du cache n’expirent après leur durée de vie de 5 minutes.
3. Structurez vos requêtes pour partager autant de contenu mis en cache que possible.
Exemple d’implémentation de la mise en cache des prompts dans un lot :
```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": "",
"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": "",
"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: ""
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: ""
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": "",
"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": "",
"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: "",
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: "",
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
{
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 = "",
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
{
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 = "",
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: "",
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: "",
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("")
.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("")
.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' => '',
'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' => '',
'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: "",
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: "",
cache_control: { type: "ephemeral" }
}
],
messages: [
{ role: "user", content: "Write a summary of Pride and Prejudice." }
]
}
}
]
)
```
Dans cet exemple, les deux requêtes du lot incluent des messages système identiques ainsi que le texte intégral d’Orgueil et Préjugés marqué avec `cache_control` afin d’augmenter la probabilité de succès du cache.
### Outils serveur et boucle agentique
Tous les [outils serveur](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/server-tools) (recherche web, récupération web, exécution de code, connecteurs MCP, conseiller et recherche d’outils) fonctionnent dans les requêtes par lots. Le worker de lots exécute la même boucle agentique côté serveur que l’API Messages synchrone.
Comme il n’y a pas de connexion ouverte à maintenir, la boucle de lot peut exécuter **plus d’itérations au cours d’un tour** qu’une requête synchrone avant de renvoyer `stop_reason: "pause_turn"`. Si un résultat de lot revient avec `pause_turn`, le tour ne s’est pas terminé ; vous pouvez le poursuivre en soumettant le contenu de l’assistant mis en pause dans une requête ultérieure (par lots ou synchrone), exactement comme indiqué dans le [modèle de continuation pause\_turn](https://platform.claude.com/docs/fr/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn).
Le worker de lots limite en outre `web_search` pour chaque organisation afin que le traitement par lots hautement simultané n’épuise pas la limite de débit de recherche web de votre organisation. Le lot réessaie automatiquement les requêtes limitées ; vous n’avez pas besoin de gérer cela vous-même, mais les très grands lots de recherche web pourraient prendre plus de temps à se terminer.
### Sortie étendue (bêta)
L’en-tête bêta `output-300k-2026-03-24` porte le plafond de `max_tokens` à 300 000 pour les requêtes par lots utilisant 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 ou Claude Haiku 5.5. Incluez cet en-tête pour générer des sorties bien plus longues que la limite standard de 128k `max_tokens` en un seul tour.
La sortie étendue est disponible uniquement sur l’API Message Batches, et non sur l’API Messages synchrone. Elle est prise en charge sur la Claude API et Claude Platform on AWS, et n’est actuellement pas disponible sur Amazon Bedrock, Claude Models on Google Cloud (Google managed) ou Microsoft Foundry.
Utilisez la sortie étendue pour la génération de contenus longs tels que des brouillons de la longueur d’un livre et de la documentation technique, l’extraction exhaustive de données structurées, de grands squelettes de génération de code et de longues chaînes de raisonnement.
Une seule génération de 300k tokens peut prendre plus d’une heure, planifiez donc vos soumissions de lots en tenant compte de la fenêtre de traitement de 24 heures. La tarification standard des lots (50 pour cent des prix standard de l’API) s’applique.
```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
```
### Bonnes pratiques pour un traitement par lots efficace
Pour utiliser efficacement l’API Batches :
* Surveillez régulièrement le statut de traitement des lots et implémentez une logique de nouvelle tentative appropriée pour les requêtes ayant échoué.
* Utilisez des valeurs `custom_id` significatives pour associer facilement les résultats aux requêtes, car l’ordre n’est pas garanti.
* Envisagez de diviser les très grands ensembles de données en plusieurs lots pour une meilleure gestion.
* Effectuez un essai avec une seule structure de requête via l’API Messages pour éviter les erreurs de validation.
### Résolution des problèmes courants
En cas de comportement inattendu :
* Vérifiez que la taille totale de la requête par lots ne dépasse pas 256 Mo. Si la taille de la requête est trop importante, vous pourriez obtenir une erreur 413 `request_too_large`.
* Vérifiez que vous utilisez des [modèles pris en charge](https://platform.claude.com/docs/fr/build-with-claude/batch-processing#supported-models) pour toutes les requêtes du lot.
* Assurez-vous que chaque requête du lot possède un `custom_id` unique.
* Assurez-vous que moins de 29 jours se sont écoulés depuis l’heure `created_at` du lot (et non l’heure `ended_at` du traitement). Si plus de 29 jours se sont écoulés, les résultats ne seront plus consultables.
* Confirmez que le lot n’a pas été annulé.
Notez que l’échec d’une requête dans un lot n’affecte pas le traitement des autres requêtes.
## Stockage et confidentialité des lots
* **Isolation par espace de travail :** les lots sont isolés au sein de l’espace de travail dans lequel ils sont créés. Ils ne sont accessibles que par les requêtes API de ce même espace de travail, ou par les utilisateurs autorisés à consulter les lots de l’espace de travail dans la Console.
* **Disponibilité des résultats :** les résultats des lots sont disponibles pendant 29 jours après la création du lot, ce qui laisse amplement le temps de les récupérer et de les traiter.
## FAQ
Le traitement des lots peut prendre jusqu’à 24 heures, mais beaucoup se terminent plus tôt. Le temps de traitement réel dépend de la taille du lot, de la demande actuelle et de votre volume de requêtes. Il est possible qu’un lot expire et ne se termine pas dans les 24 heures.
Consultez [Modèles pris en charge](https://platform.claude.com/docs/fr/build-with-claude/batch-processing#supported-models) pour la liste des modèles pris en charge.
Oui, l’API Message Batches prend en charge presque toutes les fonctionnalités disponibles dans l’API Messages, y compris la plupart des fonctionnalités bêta. Un petit nombre de paramètres (`stream`, `speed`, `fallbacks` et `max_tokens: 0`) ne sont pas pris en charge. Consultez [Ce qui peut être traité par lots](https://platform.claude.com/docs/fr/build-with-claude/batch-processing#what-can-be-batched) pour la liste complète.
L’API Message Batches offre une réduction de 50 pour cent sur toute l’utilisation par rapport aux prix standard de l’API. Cela s’applique aux tokens d’entrée, aux tokens de sortie et à tous les tokens spéciaux. Pour en savoir plus sur la tarification, consultez [Tarification](https://claude.com/pricing#anthropic-api).
Non, une fois qu’un lot a été soumis, il ne peut pas être modifié. Si vous devez apporter des modifications, annulez le lot en cours et soumettez-en un nouveau. Notez que l’annulation peut ne pas prendre effet immédiatement.
L’API Message Batches possède des limites de débit basées sur les requêtes HTTP, en plus de limites sur le nombre de requêtes en attente de traitement. Consultez [Limites de débit de l’API Message Batches](https://platform.claude.com/docs/fr/api/rate-limits#message-batches-api). L’utilisation de l’API Batches n’affecte pas les limites de débit de l’API Messages.
Lorsque vous récupérez les résultats, chaque requête possède un champ `result` indiquant si elle a réussi (`succeeded`), a rencontré une erreur (`errored`), a été annulée (`canceled`) ou a expiré (`expired`). Pour les résultats `errored`, des informations supplémentaires sur l’erreur sont fournies. Consultez l’objet de réponse d’erreur dans la [référence de l’API](https://platform.claude.com/docs/fr/api/messages/batches/create).
L’API Message Batches est conçue avec de solides mesures de confidentialité et de séparation des données :
1. Les lots et leurs résultats sont isolés au sein de l’espace de travail dans lequel ils ont été créés. Cela signifie qu’ils ne sont accessibles que par les requêtes API de ce même espace de travail.
2. Chaque requête d’un lot est traitée indépendamment, sans fuite de données entre les requêtes.
3. Les résultats ne sont disponibles que pour une durée limitée (29 jours) et suivent la [politique de conservation des données](https://support.claude.com/en/articles/7996866-how-long-do-you-store-personal-data) d’Anthropic.
4. Le téléchargement des résultats des lots dans la Console peut être désactivé au niveau de l’organisation ou par workspace.
Oui, il est possible d’utiliser la mise en cache des prompts avec l’API Message Batches. Cependant, étant donné que les requêtes asynchrones par lots peuvent être traitées simultanément et dans n’importe quel ordre, les succès du cache sont fournis dans la mesure du possible.
## Disponibilité
Traitement par lots est disponible sur tous les modèles.
### Prise en charge de l’API
#### [Messages API](https://platform.claude.com/docs/fr/build-with-claude/working-with-messages)
* Disponibilité : Disponible
| Statut | Plateformes cloud |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Disponible | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/fr/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/fr/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |
#### [Managed Agents](https://platform.claude.com/docs/fr/managed-agents/overview)
* Disponibilité : Non disponible
### Traitement des données
[Présentation du traitement des données](https://platform.claude.com/docs/fr/manage-claude/api-and-data-retention#feature-eligibility)
| Élément | Zéro conservation des données | HIPAA |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| Statut | Non éligible | Non éligible |
| Détails | Conservation de 29 jours ; stockage asynchrone requis. [En savoir plus](https://platform.claude.com/docs/fr/build-with-claude/batch-processing#data-retention) | — |
Points de terminaison concernés :
* `/v1/messages/batches`
Le traitement par lots stocke les données des requêtes et des réponses jusqu’à 29 jours après la création du lot. Vous pouvez supprimer un lot de messages à tout moment après le traitement en utilisant le point de terminaison [`DELETE /v1/messages/batches/{batch_id}`](https://platform.claude.com/docs/fr/api/messages/batches/delete). Pour supprimer un lot en cours, annulez-le d’abord. Le traitement asynchrone nécessite le stockage côté serveur des entrées et des sorties jusqu’à l’achèvement du lot et la récupération des résultats.
## Étapes suivantes
Obtenez des citations naturelles pour les applications RAG en fournissant des résultats de recherche avec attribution des sources.
Réduisez les coûts et la latence en mettant en cache les préfixes de prompts partagés entre les requêtes d’un lot.