> ## Documentation Index
> Fetch the complete documentation index at: https://docs.priceos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Usage (Batch)

> Record usage for multiple events (max 100).



## OpenAPI

````yaml POST /v1/usage/batch
openapi: 3.1.0
info:
  title: PriceOS Public API
  version: 1.0.0
servers: []
security: []
paths:
  /v1/usage/batch:
    post:
      summary: Track usage batch
      description: Record usage for multiple events (max 100).
      parameters:
        - schema:
            type: string
            description: API key from your PriceOS dashboard.
          required: true
          description: API key from your PriceOS dashboard.
          name: x-api-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  items:
                    type: object
                    properties:
                      customerId:
                        type: string
                        description: >-
                          Internal customer ID. If the customer ID does not
                          exist yet, it will be created.
                      featureKey:
                        type: string
                        description: Feature key to track usage for.
                      amount:
                        type: number
                        default: 1
                        description: >-
                          Usage amount to record. Defaults to 1. Supports
                          positive or negative values.
                      eventKey:
                        type: string
                        description: >-
                          Stable unique identifier for this event. Reuse it on
                          retries and for deduplication.
                      occurredAt:
                        type: integer
                        description: Unix timestamp (ms) when the event occurred.
                      metadata:
                        type: object
                        additionalProperties:
                          type: string
                        description: >-
                          Optional metadata for the event (string key/value
                          pairs).
                    required:
                      - customerId
                      - featureKey
                  minItems: 1
                  maxItems: 100
                  description: Batch usage events.
              required:
                - events
      responses:
        '200':
          description: Usage batch recorded
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      oneOf:
                        - type: object
                          properties:
                            success:
                              type: boolean
                              enum:
                                - true
                              description: >-
                                Whether the usage event was processed
                                successfully.
                            result:
                              type: object
                              properties:
                                applied:
                                  type: boolean
                                  description: Whether the usage event was applied.
                                used:
                                  type:
                                    - number
                                    - 'null'
                                  description: Updated usage total, if applicable.
                                eventId:
                                  type:
                                    - string
                                    - 'null'
                                  format: uuid
                                  description: Usage event ID when available.
                                reason:
                                  type:
                                    - string
                                    - 'null'
                                  description: Reason the usage event was not applied.
                              required:
                                - applied
                                - used
                              description: Usage result for the event.
                          required:
                            - success
                            - result
                        - type: object
                          properties:
                            success:
                              type: boolean
                              enum:
                                - false
                              description: Whether the usage event failed.
                            error:
                              type: string
                              description: Error message for the failed event.
                            status:
                              type: integer
                              description: HTTP status code for the error.
                          required:
                            - success
                            - error
                            - status
                      description: Batch usage result entry.
                    description: Batch usage results, in the same order as the request.
                  hasErrors:
                    type: boolean
                    description: Whether any usage events failed.
                required:
                  - results
                  - hasErrors
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message.
                required:
                  - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message.
                required:
                  - error
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message.
                required:
                  - error
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message.
                required:
                  - error
      x-codeSamples:
        - lang: typescript
          label: Node.js
          source: >-
            import { PriceOS } from "priceos";

            import type { MyFeatures } from "./priceos.types";


            const priceos = new
            PriceOS<MyFeatures>(process.env.PRICEOS_API_KEY!);


            const result = await priceos.usage.trackBatch({
              events: [
                {
                  customerId: "customer_123",
                  featureKey: "api_calls",
                  eventKey: "evt_1",
                },
                {
                  customerId: "customer_123",
                  featureKey: "api_calls",
                  amount: 2,
                  eventKey: "evt_2",
                },
              ],
            });
        - lang: bash
          label: cURL
          source: |-
            curl -X POST "https://api.priceos.com/v1/usage/batch" \
              -H "x-api-key: PRICEOS_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "events": [
                  {
                    "customerId": "customer_123",
                    "featureKey": "api_calls",
                    "eventKey": "evt_1"
                  },
                  {
                    "customerId": "customer_123",
                    "featureKey": "api_calls",
                    "amount": 2,
                    "eventKey": "evt_2"
                  }
                ]
              }'

````