---
title: "Bulk create spans"
method: POST
path: "/api/request-logs/bulk/"
tags: ["spans"]
---

# Bulk create spans

`POST /api/request-logs/bulk/`

Create up to 500 spans in one request. Each item in `logs` accepts the same fields as the [single-span create operation](/docs/apis/spans/create-span). Rows are processed independently: one invalid row does not prevent the remaining rows from being accepted. A response is `201 Created` whenever at least one row is accepted, including partial success; inspect `error_count` and `errors` on every response. `success_count` means the row passed synchronous validation and was accepted for ingestion.

For API-key authentication, this endpoint is limited to 30 requests per minute per organization, shared across all API keys in that organization. JWT requests are limited per user. At the 500-row maximum, the API-key limit allows up to approximately 15,000 accepted rows per minute. Metadata keys beginning with `_` are reserved for platform use and are omitted from customer-facing span and trace responses, so they do not round-trip through read APIs.

## Headers

- `Authorization` string, required

## Request body

- object
  - `logs` SpanCreateRequest[], required — Non-empty array of span payloads. Each object uses the same schema as `POST /api/request-logs/`.

## Response `201`

At least one row was accepted. This status is also used for partial success; inspect the response counts and indexed errors.

- BulkOperationResponse — Canonical result envelope for a bulk operation.
  - `success_count` integer, required — Number of items successfully processed.
  - `error_count` integer, required — Number of items that failed.
  - `errors` BulkItemError[], required — Item-level failures, keyed by zero-based input index.
    - `index` integer, required — Zero-based index of the failed item in the submitted array.
    - `error` string, required — Error message for the failed item.

## Other responses

- `400` — Every row failed, the `logs` envelope was missing or malformed, the list was empty, or the organization is blocked.
- `401` — Unauthorized - Missing or invalid authentication
- `403` — Forbidden - The authenticated principal cannot access this organization
- `422` — The batch contains more than 500 rows.
- `429` — Rate limit exceeded.

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)