---
title: "Record usage signals in bulk (V2 - Clean field names)"
method: POST
path: "/usage/v2/signals/bulk"
tags: ["usage"]
---

# Record usage signals in bulk (V2 - Clean field names)

`POST /usage/v2/signals/bulk`

## Request

- Base URL: `https://api.agentpaid.io/api/v1`
- URL: `https://api.agentpaid.io/api/v1/usage/v2/signals/bulk`
- Auth: HTTP bearer

## Request body

- object
  - `signals` SignalV2[]
    - `event_name` string, required: The name of the event being tracked
    - `product_id` string: Paid's display ID for the product (e.g., prod_abc123). Cannot be used with external_product_id. Either this or external_product_id is required.
    - `external_product_id` string: Your system's product ID. Cannot be used with product_id. Either this or product_id is required.
    - `customer_id` string: Paid's display ID for the customer (e.g., cus_xyz789). Cannot be used with external_customer_id. Either this or external_customer_id is required.
    - `external_customer_id` string: Your system's customer ID. Cannot be used with customer_id. Either this or customer_id is required.
    - `data` object: Optional additional data/metadata for the signal
    - `idempotency_key` string: A unique key to ensure idempotent signal processing. If a signal with the same idempotency key has already been processed, the entire batch will be rejected with a 409 Conflict error.

## Response `201`

Success response

- UsageUsageRecordBulkV2Response201: Empty response body

## Other responses

- `400`: Bad request - Each signal must provide exactly one customer ID (customer_id OR external_customer_id) and exactly one product ID (product_id OR external_product_id). Providing both or neither will result in an error.
- `409`: Conflict - One or more signals have idempotency keys that have already been used. The entire batch is rejected.

---

[API](https://skmtc.dev/paid/apis/paid-2.md) - [All operations](https://skmtc.dev/paid/apis/paid-2/llms.txt) - [OpenAPI document](https://skmtc.dev/paid/apis/paid-2/revisions/dbdf4a60ed27?raw)