---
title: "Custom events detail listing"
method: GET
path: "/api/reports/events"
tags: ["Reports"]
---

# Custom events detail listing

`GET /api/reports/events`

## Request

- Base URL: `https://go.urbanairship.com`
- URL: `https://go.urbanairship.com/api/reports/events`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `http://oauth2.{domain}.com/token` scopes: `rpt`
- TypeScript: <https://skmtc.dev/airship/apis/airship-api/docs/api/reports/events/get.ts> (a function with typed inputs; its response is checked against the schema)

Get a summary of custom event counts and values, by custom event, within the specified time period.

## Query parameters

- `start` string, date-time, required
- `end` string, date-time, required
- `precision` 'HOURLY' | 'DAILY' | 'MONTHLY'
- `page` integer
- `page_size` integer

## Response `200`

Returned on success, with the JSON representation of the events in the body of the response.

- object: The response body for custom events detail listing.
  - `events` object[]: An array of custom events and its details.
    - `conversion` 'direct' | 'indirect': The type of conversion. `direct` means the conversion happened during an app session that started by tapping a push notification (direct open). `indirect` means the conversion happened during an app session that wasn't direct, or was submitted by the app via API, and occurred within 12 hours of receiving a push.
    - `count` integer: Number of instances of this event.
    - `location` string: The source from which the event originates, e.g., Message Center, Landing Page, custom, etc.
    - `name` string: The name of the custom event.
    - `value` integer: The value generated by the event.
  - `next_page` string, url: There might be more than one page of results for this listing. Follow this URL if it is present to the next batch of results.
  - `ok` boolean: Success.
  - `prev_page` string, url: Link to the previous page, if available.
  - `total_count` integer: Sum of all the count fields in the above array.
  - `total_value` integer: Sum of all the value fields in the above array.

## Other responses

- `400`: There was a parsing or validation error in the request. Bad Request errors typically include `path` and `location` in the response to help you find the cause of the error.
- `401`: Authentication information (the app key and secret or bearer token) was either incorrect or missing.
- `403`: Authentication was correct, but the user does not have permission to access the requested API, e.g., if the feature in question is not included in your pricing plan.

## Changes

- **2025-08-28** `3304568aaadc`: 2 breaking
  - for the `query` request parameter `end`, the format changed from no format to `date-time`
  - for the `query` request parameter `start`, the format changed from no format to `date-time`
  - …this revision’s changelog is incomplete

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/reports/events/get.md)

---

[API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)