---
title: "Get a list of usage events with multiple query options"
method: GET
path: "/events"
tags: ["Event Management"]
---

# Get a list of usage events with multiple query options

`GET /events`

## Request

- Base URL: `https://api.togai.com`
- URL: `https://api.togai.com/events`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/togaihq/apis/togai-apis/docs/events/get.ts> (a function with typed inputs; its response is checked against the schema)

This API let’s you to fetch a list of events with multiple query parameters

## Query parameters

- `nextToken` string
- `status` string
- `account_id` string
- `schema_name` string
- `pageSize` integer

## Response `200`

Success response

- GetEventsResponse: Get batch events response
  - `events` EventWithStatus[], required
    - `referenceId` string, required: Unique id generated by Togai to identify an event uniquely
    - `eventPayload` Event, required: Contents of the event
      - `schemaName` string, required: Name of the Event Schema. Know more about [event schema](https://docs.togai.com/docs/event-schemas)
      - `id` string: Togai restricts users to ingest events with same id within a period of *45 days*. This restriction is common for [/entitled API](/api-reference/entitlements/ingest-event-if-a-user-is-entitled-to-a-feature), [/ingest API](/api-reference/event-ingestion/ingest-events-to-togai) and [/ingestBatch API](/api-reference/event-ingestion/ingest-events-to-togai-in-batch). i.e, an id used on /ingest API will not be allowed on /ingestBatch or /entitled APIs
      - `timestamp` string, date-time, required: Source time stamp of the event. This timestamp must be in ISO 8601 format.
      - `accountId` string, required: The event will be associated with the provided account
      - `attributes` Attribute[], required: Attributes are numeric values. It can be usage metric which you push to Togai
        - `name` string, required: Name of the event attribute
        - `value` string, required: Value of the event attribute
        - `unit` string: Unit with which the attribute value was measured. Natively supported units - "Meters, Miles, Kilometers, Grams, Kilograms, ounces, Pounds, Minutes, Hours, Seconds, Milliseconds, Microseconds, None". Clients are free to add any other custom units.
      - `dimensions` Dimensions, required: Dimensions are tags/labels associated with the events.
    - `ingestionStatus` IngestionStatus, required: Status about the event ingestion.
      - `status` 'INGESTION_IN_PROGRESS' | 'INGESTION_FAILED' | 'INGESTION_FAILED_SCHEMA_NOT_DEFINED' | 'INGESTION_FAILED_ENRICHMENT_FAILED' | 'INGESTION_FAILED_UNITS_INVALID' | 'INGESTION_COMPLETED_NO_MATCHING_METERS' | 'INGESTION_COMPLETED_EVENT_METERED' | 'INGESTION_COMPLETED_EVENT_NOT_METERED' | 'INGESTION_FAILED_PAST_GRACE_PERIOD' | 'INGESTION_FAILED_ACCOUNT_NOT_FOUND' | 'INGESTION_FAILED_DUPLICATE_EVENT' | 'INGESTION_FAILED_NO_EVENT_ID' | 'INGESTION_FAILED_INVALID_NAMED_LICENSE_EVENT' | 'INGESTION_FAILED_INSUFFICIENT_CREDITS' | 'REVERTED' | 'UNKNOWN', required: Ingestion status
      - `statusDescription` string
    - `customerId` string: The associated account belongs to this customer
    - `source` EventSource: Source of ingestion of event
      - `id` string, required: Unique identifier representing the source
      - `type` string, required: Type of source
    - `createdAt` string, date-time, required: Created time stamp of the event. This timestamp must be in ISO 8601 format.
  - `nextToken` string

## Other responses

- `400`: Bad request. Please check the response message for failure details.
- `401`: Credential is not valid. Please check the response message for failure details.
- `403`: Credential does not have access to list events.
- `422`: Unable to process the query parameters provided. Please check our docs for the api limits - https://togai.io/docs/limits.
- `429`: Request throttled. Please check the response message on the failure details.
- `default`: Error response

## Changes

- **2024-05-14** `d078d3562056`: 1 breaking, 1 warning
  - the `events/items/eventPayload/dimensions/additionalProperties/` response property's maxLength was increased from `50` to `200` for the response status `200`
  - added the new `INGESTION_FAILED_INSUFFICIENT_CREDITS` enum value to the `events/items/ingestionStatus/status` response property for the response status `200`
- **2024-03-11** `cc0b10fb537e`: 1 warning
  - added the new `INGESTION_FAILED_INVALID_NAMED_LICENSE_EVENT` enum value to the `events/items/ingestionStatus/status` response property for the response status `200`
- **2024-03-01** `6fb940b0dad9`: 1 breaking, 1 warning
  - the response property `events/items/eventPayload/id` became optional for the status `200`
  - added the new `INGESTION_FAILED_NO_EVENT_ID` enum value to the `events/items/ingestionStatus/status` response property for the response status `200`
- **2023-10-16** `898bb5f2ce0c`: 1 warning, 1 info
  - added the new `REVERTED` enum value to the `events/items/ingestionStatus/status` response property for the response status `200`
  - added the required property `events/items/referenceId` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/togaihq/apis/togai-apis/changes/events/get.md)

---

[API](https://skmtc.dev/togaihq/apis/togai-apis.md) - [All operations](https://skmtc.dev/togaihq/apis/togai-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/togaihq/apis/togai-apis/revisions/442f5d8f4aa0?raw)