---
title: "Ingest Events"
method: POST
path: "/v1/events/ingest"
tags: ["events", "public"]
---

# Ingest Events

`POST /v1/events/ingest`

Ingest batch of events.

**Scopes**: `events:write`

## Request body

- EventsIngest
  - `events` union[], required — List of events to ingest.
    - union
      - EventCreateCustomer
        - `timestamp` string, date-time — The timestamp of the event.
        - `name` string, required — The name of the event.
        - `organization_id` string, uuid4, nullable — The organization ID.
        - `external_id` string, nullable — Your unique identifier for this event. Useful for deduplication and parent-child relationships.
        - `parent_id` string, nullable — The ID of the parent event. Can be either a Polar event ID (UUID) or an external event ID.
        - `metadata` EventMetadataInput
          - `_cost` CostMetadataInput
            - `amount` union, required — The amount in cents.
              - …
            - `currency` string, required — The currency. Currently, only `usd` is supported.
          - `_llm` LLMMetadata
            - `vendor` string, required — The vendor of the event.
            - `model` string, required — The model used for the event.
            - `prompt` string, nullable — The LLM prompt used for the event.
            - `response` string, nullable — The LLM response used for the event.
            - `input_tokens` integer, required — The number of LLM input tokens used for the event.
            - `cached_input_tokens` integer — The number of LLM cached tokens that were used for the event.
            - `output_tokens` integer, required — The number of LLM output tokens used for the event.
            - `total_tokens` integer, required — The total number of LLM tokens used for the event.
        - `customer_id` string, uuid4, required — ID of the customer in your Polar organization associated with the event.
        - `member_id` string, uuid4, nullable — ID of the member within the customer's organization who performed the action. Used for member-level attribution in B2B.
      - EventCreateExternalCustomer
        - `timestamp` string, date-time — The timestamp of the event.
        - `name` string, required — The name of the event.
        - `organization_id` string, uuid4, nullable — The organization ID.
        - `external_id` string, nullable — Your unique identifier for this event. Useful for deduplication and parent-child relationships.
        - `parent_id` string, nullable — The ID of the parent event. Can be either a Polar event ID (UUID) or an external event ID.
        - `metadata` EventMetadataInput
          - `_cost` CostMetadataInput
            - `amount` union, required — The amount in cents.
              - …
            - `currency` string, required — The currency. Currently, only `usd` is supported.
          - `_llm` LLMMetadata
            - `vendor` string, required — The vendor of the event.
            - `model` string, required — The model used for the event.
            - `prompt` string, nullable — The LLM prompt used for the event.
            - `response` string, nullable — The LLM response used for the event.
            - `input_tokens` integer, required — The number of LLM input tokens used for the event.
            - `cached_input_tokens` integer — The number of LLM cached tokens that were used for the event.
            - `output_tokens` integer, required — The number of LLM output tokens used for the event.
            - `total_tokens` integer, required — The total number of LLM tokens used for the event.
        - `external_customer_id` string, required — ID of the customer in your system associated with the event.
        - `external_member_id` string, nullable — ID of the member in your system within the customer's organization who performed the action. Used for member-level attribution in B2B.

## Response `200`

Successful Response

- EventsIngestResponse
  - `inserted` integer, required — Number of events inserted.
  - `duplicates` integer — Number of duplicate events skipped.

## Other responses

- `422` — Validation Error

---

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