Batch Processing

Batch processing (batching) allows you to send multiple message requests in a single batch and retrieve the results later (within up to 1 hour). The main goals are to reduce costs by up to 50% and increase throughput for analytical or offline workloads.

To use batch processing, several endpoints are available:

Create a message batch

https://api.aimlapi.com/batches

Get status or results of a batch

https://api.aimlapi.com/batches?batch_id={batch_id}

Cancel a batch

https://api.aimlapi.com/batches/cancel/{batch_id}

This API supports all Claude chat models available on our platform.

Create a batch

post

Body

Responses

200Success

application/json

idstringRequired

Unique identifier of the batch.

Example: kgTRCVoAz4GwrHWIOFZjg

typestringRequired

Object type.

Example: message_batch

processing_statusstringRequired

Current processing status of the batch.

Example: in_progress

ended_atstring · date-time · nullableOptional

Timestamp when the batch finished processing, if completed.

created_atstring · date-timeRequired

Timestamp when the batch was created.

Example: 2026-05-04T17:27:37.468424+00:00

expires_atstring · date-timeRequired

Timestamp when the batch will expire if not completed.

Example: 2026-05-05T17:27:37.468424+00:00

archived_atstring · date-time · nullableOptional

Timestamp when the batch was archived, if applicable.

cancel_initiated_atstring · date-time · nullableOptional

Timestamp when cancellation was initiated, if applicable.

results_urlstring · nullableOptional

URL to download batch results once processing is complete.

200Success

{
  "id": "kgTRCVoAz4GwrHWIOFZjg",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 3,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-05-04T17:27:37.468424+00:00",
  "expires_at": "2026-05-05T17:27:37.468424+00:00",
  "archived_at": "2026-01-01T00:00:00.000Z",
  "cancel_initiated_at": "2026-01-01T00:00:00.000Z",
  "results_url": "text"
}

Code Example (Python)

Response

Get status or results of a batch

get

Query parameters

batch_idstringRequired

The ID of the batch to retrieve its status and results.

Example: <REPLACE_WITH_YOUR_BATCH_ID>

Responses

200Success

application/json

idstringRequired

Unique identifier of the batch.

Example: msgbatch_01McVJYhQd3Wiuqrac6y9PrX

typestringRequired

Object type.

Example: message_batch

processing_statusstringRequired

Current processing status of the batch.

Example: in_progress

ended_atstring · date-time · nullableOptional

Timestamp when the batch finished processing, if completed.

created_atstring · date-timeRequired

Timestamp when the batch was created.

Example: 2025-10-24T13:49:11.902215+00:00

expires_atstring · date-timeRequired

Timestamp when the batch will expire if not completed.

Example: 2025-10-25T13:49:11.902215+00:00

cancel_initiated_atstring · date-time · nullableOptional

Timestamp when cancellation was initiated, if applicable.

results_urlstring · nullableOptional

URL to download batch results once processing is complete.

200Success

{
  "id": "msgbatch_01McVJYhQd3Wiuqrac6y9PrX",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 3,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2025-10-24T13:49:11.902215+00:00",
  "expires_at": "2025-10-25T13:49:11.902215+00:00",
  "cancel_initiated_at": "2026-01-01T00:00:00.000Z",
  "results_url": "text"
}

Code Example (Python)

Response #1 (status: generating)

Response #2 (status: if already cancelled)

Response #3 (if already finished)

Cancel a batch

post

Path parameters

batch_idstringRequired

The ID of the batch to cancel.

Example: <REPLACE_WITH_YOUR_BATCH_ID>

Responses

200Success

application/json

idstringRequired

Unique identifier of the batch.

Example: fe91QH0tkQwaJSXo0q77O

statusstringRequired

Final status of the batch after cancellation.

Example: cancelled

outputany · nullableRequired

Batch output, if available.

usageobject[]Required

Usage details for the batch.

200Success

{
  "id": "fe91QH0tkQwaJSXo0q77O",
  "status": "cancelled",
  "output": null,
  "usage": []
}

Code Example (Python)

Response #1 (successfully cancelled)

Response #2 (if already finished)

PreviousWeb Search

NextRequest Tracing and Cost Headers

Last updated 3 months ago

Was this helpful?

[
  {
    "custom_id": "test-01",
    "result": {
      "type": "succeeded",
      "message": {
        "model": "claude-sonnet-4-20250514",
        "id": "msg_01NGpcFgpg4CoupjDTDYD68i",
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Here's a structured approach to learning NestJS:\n\n## Prerequisites\n- **JavaScript/TypeScript**: Strong foundation in modern JS and TypeScript\n- **Node.js basics**: Understanding of Node.js runtime and npm\n- **Express.js**: Basic knowledge helpful (NestJS builds on Express concepts)\n- **Decorators**: Understanding TypeScript decorators\n\n## Learning Path\n\n### 1. **Start with Fundamentals**\n```bash\n# Install NestJS CLI\nnpm i -g @nestjs/cli\n\n# Create your first project\nnest new my-first-project\n```\n\n**Core Concepts to Master:**\n- Controllers and routing\n- Services and dependency injection\n- Modules and application structure\n- Decorators (`@Controller`, `@Injectable`, `@Module`)\n\n### 2. **Essential Topics** (in order)\n- **Controllers**: Handle HTTP requests\n- **Providers/Services**: Business logic and data access\n- **Modules**: Organize application structure\n- **Middleware**: Request/response processing\n- **Exception Filters**: Error handling\n- **Pipes**: Data validation and transformation\n- **Guards**: Authentication and authorization\n- **Interceptors**: AOP-style request/response manipulation\n\n### 3. **Intermediate Concepts**\n- **Database Integration**: TypeORM, Prisma, or Mongoose\n- **Authentication**: JWT, Passport strategies\n- **Configuration**: Environment variables, config modules\n- **Validation**: Class-validator and class-transformer\n- **Testing**: Unit and integration testing\n- **GraphQL**: If relevant to your projects\n\n### 4. **Advanced Topics**\n- **Microservices**: Inter-service communication\n- **WebSockets**: Real-time applications\n- **Task Scheduling**: Cron jobs and queues\n- **Custom Decorators**: Creating reusable decorators\n- **Performance**: Caching, optimization techniques\n\n## Learning Resources\n\n### **Official Documentation**\n- [NestJS Official Docs](https://docs.nestjs.com/) - Best starting point\n- [NestJS GitHub Examples](https://github.com/nestjs/nest/tree/master/sample)\n\n### **Courses**\n- **Udemy**: \"NestJS: The Complete Developer's Guide\"\n- **Pluralsight**: NestJS courses\n- **YouTube**: Free tutorials (Marius Espejo, Traversy Media)\n\n### **Books**\n- \"NestJS: A Progressive Node.js Framework\" by various authors\n\n## Practical Learning Steps\n\n### Week 1-2: Basics\n```typescript\n// Create a simple REST API\n@Controller('cats')\nexport class CatsController {\n  @Get()\n  findAll(): string {\n    return 'This action returns all cats';\n  }\n  \n  @Post()\n  create(@Body() createCatDto: CreateCatDto) {\n    return 'This action adds a new cat';\n  }\n}\n```\n\n### Week 3-4: Database Integration\n```typescript\n// Add database operations\n@Injectable()\nexport class CatsService {\n  constructor(\n    @InjectRepository(Cat)\n    private catsRepository: Repository<Cat>,\n  ) {}\n\n  async findAll(): Promise<Cat[]> {\n    return this.catsRepository.find();\n  }\n}\n```\n\n### Week 5-6: Authentication & Validation\n```typescript\n// Add guards and validation\n@Controller('cats')\n@UseGuards(JwtAuthGuard)\nexport class CatsController {\n  @Post()\n  @UsePipes(ValidationPipe)\n  create(@Body() createCatDto: CreateCatDto) {\n    return this.catsService.create(createCatDto);\n  }\n}\n```\n\n## Hands-on Projects\n\n1. **Todo API** - Basic CRUD operations\n2. **Blog API** - Users, posts, comments with authentication\n3. **E-commerce API** - Products, orders, payments\n4. **Chat Application** - WebSockets integration\n5. **Microservices Project** - Multiple connected services\n\n## Best Practices\n\n- Follow NestJS architectural patterns\n- Use TypeScript features effectively\n- Implement proper error handling\n- Write tests from the beginning\n- Use DTOs for data validation\n- Follow SOLID principles\n\n## Tips for Effective Learning\n\n1. **Build Projects**: Don't just read, code along\n2. **Join Community**: NestJS Discord, Reddit communities\n3. **Read Source Code**: Examine well-"
          }
        ],
        "stop_reason": "max_tokens",
        "stop_sequence": null,
        "stop_details": null,
        "usage": {
          "input_tokens": 13,
          "cache_creation_input_tokens": 0,
          "cache_read_input_tokens": 0,
          "cache_creation": {
            "ephemeral_5m_input_tokens": 0,
            "ephemeral_1h_input_tokens": 0
          },
          "output_tokens": 1024,
          "service_tier": "batch",
          "inference_geo": "not_available"
        }
      }
    }
  },
  {
    "custom_id": "test-02",
    "result": {
      "type": "succeeded",
      "message": {
        "model": "claude-sonnet-4-5-20250929",
        "id": "msg_018DPteVhGrDVKYWiYUQbddN",
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "# How to Learn React.js\n\n## 1. **Prerequisites**\nBefore diving into React, make sure you're comfortable with:\n- **HTML & CSS** - Basic web structure and styling\n- **JavaScript (ES6+)** - Functions, arrays, objects, arrow functions, destructuring, modules\n- **DOM basics** - Understanding how the browser renders content\n\n## 2. **Learning Path**\n\n### **Phase 1: Fundamentals**\n- **JSX syntax** - HTML-like syntax in JavaScript\n- **Components** - Functional components (start here)\n- **Props** - Passing data between components\n- **State** - Managing component data with `useState`\n- **Event handling** - onClick, onChange, etc.\n- **Conditional rendering** - Showing/hiding elements\n- **Lists & keys** - Rendering arrays of data\n\n### **Phase 2: Intermediate Concepts**\n- **useEffect hook** - Side effects and lifecycle\n- **Forms & controlled components**\n- **Component composition** - Building reusable components\n- **Props drilling & lifting state up**\n- **Custom hooks** - Reusable logic\n- **useContext** - Avoiding prop drilling\n\n### **Phase 3: Advanced Topics**\n- **React Router** - Navigation between pages\n- **State management** - Redux, Zustand, or Context API\n- **API calls** - Fetching data with fetch/axios\n- **Performance optimization** - useMemo, useCallback, React.memo\n- **TypeScript with React** (optional but recommended)\n\n## 3. **Recommended Resources**\n\n### **Official Documentation**\n- [React.dev](https://react.dev) - Best starting point (new interactive tutorial)\n\n### **Free Courses**\n- freeCodeCamp React course (YouTube)\n- Scrimba's Learn React for free\n- Codecademy React course\n\n### **Paid Courses** (optional)\n- Udemy: Maximilian Schwarzm\u00fcller's React course\n- Frontend Masters\n- Epic React by Kent C. Dodds\n\n## 4. **Practical Steps**\n\n1. **Set up your environment**\n   ```bash\n   npx create-react-app my-app\n   # or use Vite (faster)\n   npm create vite@latest my-app -- --template react\n   ```\n\n2. **Build projects** (most important!)\n   - Todo list app\n   - Weather app (API integration)\n   - E-commerce product page\n   - Movie search app\n   - Personal portfolio\n\n3. **Practice daily** - Even 30 minutes consistently beats occasional long sessions\n\n4. **Read others' code** - Explore GitHub repositories\n\n5. **Join communities**\n   - Reddit: r/reactjs\n   - Discord: Reactiflux\n   - Stack Overflow\n\n## 5. **Common Beginner Mistakes to Avoid**\n- Don't mutate state directly\n- Don't skip learning JavaScript fundamentals\n- Don't jump to Redux too early\n- Don't copy-paste without understanding\n\n## 6. **Timeline**\n- **Basics**: 2-3 weeks\n- **Job-ready**: 3-6 months with consistent practice\n- **Proficiency**: 1+ year of building real projects\n\n**Start building projects as soon as possible - that's where real learning happens!**"
          }
        ],
        "stop_reason": "end_turn",
        "stop_sequence": null,
        "stop_details": null,
        "usage": {
          "input_tokens": 14,
          "cache_creation_input_tokens": 0,
          "cache_read_input_tokens": 0,
          "cache_creation": {
            "ephemeral_5m_input_tokens": 0,
            "ephemeral_1h_input_tokens": 0
          },
          "output_tokens": 761,
          "service_tier": "batch",
          "inference_geo": "not_available"
        }
      }
    }
  }
]