---
title: "Create a batch"
method: POST
path: "/v1/batches"
tags: ["batches"]
---

# Create a batch

`POST /v1/batches`

## Request

- Base URL: `https://api.olostep.com`
- URL: `https://api.olostep.com/v1/batches`
- Auth: HTTP bearer

Starts a new batch of items to process.

## Request body

- object
  - `items` object[], required: Items to process.
    - `custom_id` union: Your identifier for the item, unique within the batch. A number is stored as its text. Must not be empty. Omit to let the API mint one (`item_<suffix>`).
      - string
      - number
    - `url` string, uri, required: URL of the item.
    - `metadata` object: Set of up to 50 key-value string pairs you can attach to the object. Echoed back unchanged.
  - `country` string: ISO 3166-1 alpha-2 country to scrape from.
  - `parser` object
    - `id` string, required
  - `links_on_page` object
    - `include_links` string[]
    - `exclude_links` string[]
  - `metadata` object: Set of up to 50 key-value string pairs you can attach to the object. Echoed back unchanged.
  - `webhook` union: Webhook config { url, events }, or a URL string. A string subscribes the batch to every batch event. Deliveries can arrive out of order: a retried batch.progress can arrive after batch.completed. Use items_url to read every item.
    - string, uri
    - object
      - `url` string, uri, required
      - `events` string[], required

## Response `200`

Default Response

- object: A batch resource.
  - `id` string, required
  - `object` 'batch', required
  - `status` string, required
  - `created` number, required
  - `completed_at` number, nullable
  - `total_urls` integer, required
  - `completed_urls` integer, required
  - `number_retried` integer
  - `parser` string, nullable
  - `country` string, nullable
  - `start_date` string
  - `metadata` object
  - `webhook` string, nullable
  - `completion_window` string
  - `credits_consumed` number, nullable
  - `cost_usd` number, nullable
  - `warning` string

## Other responses

- `400`: Default Response
- `401`: Default Response
- `402`: Default Response
- `403`: Default Response
- `429`: Default Response
- `502`: Default Response
- `504`: Default Response

## Changes

- **2026-10-19** `13c766ab100c`: 1 breaking, 1 info
  - the `webhook` request property type changed from `string` to no type, and format from `uri` to no format
  - added `subschema #1, subschema #2` to the `webhook` request property `anyOf` list
- **2026-10-19** `24c12c29fa19`: 1 breaking, 1 info
  - the `items/items/custom_id/anyOf[subschema #1]/` request property's minLength was increased from `0` to `1`
  - the request property `items/items/custom_id` became optional

[Operation history](https://skmtc.dev/olostep/apis/olostep-api/changes/v1/batches/post.md)

---

[API](https://skmtc.dev/olostep/apis/olostep-api.md) · [All operations](https://skmtc.dev/olostep/apis/olostep-api/llms.txt) · [OpenAPI document](https://skmtc.dev/olostep/apis/olostep-api/revisions/13c766ab100c?raw)