The Amplitude Dashboard REST API provides programmatic access to the same data displayed in Amplitude's dashboard charts and graphs. It returns results in JSON format and supports queries filtered by event types, user segments, cohorts, and date ranges. Developers can use this API to build custom reporting tools, export chart data, or integrate Amplitude analytics into external dashboards and business intelligence systems.
openapi: 3.1.0
info:
title: Amplitude Dashboard REST API
description: >-
The Amplitude Dashboard REST API provides programmatic access to the
same data displayed in Amplitude's dashboard charts and graphs. It
returns results in JSON format and supports queries filtered by event
types, user segments, cohorts, and date ranges. Developers can use this
API to build custom reporting tools, export chart data, or integrate
Amplitude analytics into external dashboards and business intelligence
systems.
version: '2'
contact:
name: Amplitude Support
url: https://amplitude.com/contact
termsOfService: https://amplitude.com/terms
externalDocs:
description: Amplitude Dashboard REST API Documentation
url: https://amplitude.com/docs/apis/analytics/dashboard-rest
servers:
- url: https://amplitude.com
description: Amplitude Production Server
tags:
- name: Event List
description: Event listing operations
- name: Event Segmentation
description: Event segmentation analysis operations
- name: Funnel Analysis
description: Funnel analysis operations
- name: Retention Analysis
description: Retention analysis operations
- name: Revenue Analysis
description: Revenue analysis operations
- name: User Activity
description: User activity lookup operations
security:
- basicAuth: []
paths:
/api/2/events/segmentation:
get:
operationId: getEventSegmentation
summary: Amplitude Get Event Segmentation
description: >-
Get metrics for an event with segmentation. Returns event totals,
unique users, or other metrics broken down by time intervals and
optional segment or group-by properties.
tags:
- Event Segmentation
parameters:
- $ref: '#/components/parameters/eventParam'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
- name: m
in: query
description: >-
The metric to compute. Options include uniques, totals, pct_dau,
average, histogram, sums, value_avg, or formula.
schema:
type: string
enum:
- uniques
- totals
- pct_dau
- average
- histogram
- sums
- value_avg
- formula
- name: i
in: query
description: >-
Time interval granularity. Use -300000 for real-time, 1 for daily,
7 for weekly, or 30 for monthly.
schema:
type: integer
- name: s
in: query
description: >-
Segment definitions as a JSON-encoded array of segment objects for
filtering results.
schema:
type: string
- name: g
in: query
description: >-
The property to group results by, such as a user property or event
property name.
schema:
type: string
- name: limit
in: query
description: >-
The number of group-by values to return. Default is 100, max is
1000.
schema:
type: integer
default: 100
maximum: 1000
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentationResult'
examples:
getEventSegmentation200Example:
summary: Default getEventSegmentation 200 response
x-microcks-default: true
value:
data:
series:
- {}
seriesLabels:
- {}
xValues:
- {}
'400':
description: Bad request
'401':
description: Unauthorized - invalid or missing credentials
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/funnels:
get:
operationId: getFunnelAnalysis
summary: Amplitude Get Funnel Analysis
description: >-
Get funnel drop-off and conversion rates for a sequence of events.
Each event parameter in the query string defines a step in the funnel.
tags:
- Funnel Analysis
parameters:
- $ref: '#/components/parameters/eventParam'
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
- name: n
in: query
description: >-
The conversion window in days. Default varies by project settings.
schema:
type: integer
- name: s
in: query
description: >-
Segment definitions as a JSON-encoded array.
schema:
type: string
- name: g
in: query
description: >-
The property to group results by.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FunnelResult'
examples:
getFunnelAnalysis200Example:
summary: Default getFunnelAnalysis 200 response
x-microcks-default: true
value:
data: {}
'400':
description: Bad request
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/retention:
get:
operationId: getRetentionAnalysis
summary: Amplitude Get Retention Analysis
description: >-
Get user retention for specific starting and returning actions. Returns
retention data broken down by cohort date showing the percentage of
users who returned on each subsequent day.
tags:
- Retention Analysis
parameters:
- name: se
in: query
required: true
description: >-
The starting event as a JSON-encoded object with event_type field.
schema:
type: string
- name: re
in: query
required: true
description: >-
The returning event as a JSON-encoded object with event_type field.
schema:
type: string
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
- name: rm
in: query
description: >-
Retention mode. Use bracket for N-day retention or rolling for
unbounded retention.
schema:
type: string
enum:
- bracket
- rolling
- name: s
in: query
description: >-
Segment definitions as a JSON-encoded array.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/RetentionResult'
examples:
getRetentionAnalysis200Example:
summary: Default getRetentionAnalysis 200 response
x-microcks-default: true
value:
data: {}
'400':
description: Bad request
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/useractivity:
get:
operationId: getUserActivity
summary: Amplitude Get User Activity
description: >-
Get a user's most recent events, with optional filters on event types.
Returns up to 1000 of the most recent events for a given user.
tags:
- User Activity
parameters:
- name: user
in: query
required: true
description: >-
The user_id to look up activity for.
schema:
type: string
- name: offset
in: query
description: >-
The offset for pagination. Default is 0.
schema:
type: integer
default: 0
- name: limit
in: query
description: >-
The number of events to return. Default is 1000.
schema:
type: integer
default: 1000
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserActivityResult'
examples:
getUserActivity200Example:
summary: Default getUserActivity 200 response
x-microcks-default: true
value:
userData: {}
events:
- {}
'400':
description: Bad request
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/usersearch:
get:
operationId: searchUsers
summary: Amplitude Search Users
description: >-
Search for a user by user_id, device_id, or Amplitude ID. Returns
matching user identifiers and their most recent event details.
tags:
- User Activity
parameters:
- name: user
in: query
required: true
description: >-
The user_id, device_id, or Amplitude ID to search for.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserSearchResult'
examples:
searchUsers200Example:
summary: Default searchUsers 200 response
x-microcks-default: true
value:
matches:
- user_id: {}
amplitude_id: {}
'400':
description: Bad request
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/revenue/day:
get:
operationId: getRevenueLTV
summary: Amplitude Get Revenue LTV Data
description: >-
Get revenue lifetime value (LTV) data for new users acquired during
the specified date range.
tags:
- Revenue Analysis
parameters:
- $ref: '#/components/parameters/startDate'
- $ref: '#/components/parameters/endDate'
- name: m
in: query
description: >-
The revenue metric to compute.
schema:
type: string
- name: s
in: query
description: >-
Segment definitions as a JSON-encoded array.
schema:
type: string
- name: g
in: query
description: >-
The property to group results by.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: >-
Revenue LTV data organized by cohort date.
examples:
getRevenueLTV200Example:
summary: Default getRevenueLTV 200 response
x-microcks-default: true
value:
data: {}
'400':
description: Bad request
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/events/list:
get:
operationId: listEventTypes
summary: Amplitude List Event Types
description: >-
Get the list of event types in the project along with their volume
over the last 30 days.
tags:
- Event List
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventListResult'
examples:
listEventTypes200Example:
summary: Default listEventTypes 200 response
x-microcks-default: true
value:
data:
- name: {}
totals: {}
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Use your Amplitude API key as the username and your secret key as the
password. Encode them as base64 in the format api_key:secret_key.
parameters:
eventParam:
name: e
in: query
required: true
description: >-
A JSON-encoded event object with at minimum an event_type field. For
funnel analysis, multiple e parameters define each funnel step.
schema:
type: string
startDate:
name: start
in: query
required: true
description: >-
The start date in YYYYMMDD format.
schema:
type: string
pattern: '^\d{8}$'
endDate:
name: end
in: query
required: true
description: >-
The end date in YYYYMMDD format.
schema:
type: string
pattern: '^\d{8}$'
schemas:
SegmentationResult:
type: object
properties:
data:
type: object
properties:
series:
type: array
description: >-
An array of data series, one per segment or group-by value.
items:
type: object
additionalProperties: true
seriesLabels:
type: array
description: >-
Labels corresponding to each series.
items:
type: array
items:
type: string
xValues:
type: array
description: >-
The x-axis values representing time periods.
items:
type: string
FunnelResult:
type: object
properties:
data:
type: object
description: >-
Funnel conversion data including step-by-step drop-off rates.
RetentionResult:
type: object
properties:
data:
type: object
description: >-
Retention data organized by cohort date with day-by-day return
percentages.
UserActivityResult:
type: object
properties:
userData:
type: object
description: >-
User metadata including user_id and Amplitude ID.
events:
type: array
description: >-
Array of recent events for the user.
items:
type: object
additionalProperties: true
UserSearchResult:
type: object
properties:
matches:
type: array
description: >-
Array of matching users with their identifiers.
items:
type: object
properties:
user_id:
type: string
description: >-
The user's user_id.
amplitude_id:
type: integer
format: int64
description: >-
The user's Amplitude internal ID.
EventListResult:
type: object
properties:
data:
type: array
description: >-
Array of event type objects with names and volumes.
items:
type: object
properties:
name:
type: string
description: >-
The name of the event type.
totals:
type: integer
description: >-
The total number of times this event was fired in the last
30 days.