Amplitude Retention Analysis API

openapi: 3.2.0
info:
  title: Amplitude Dashboard REST Retention Analysis 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
servers:
- url: https://amplitude.com
  description: Amplitude Production Server
security:
- basicAuth: []
tags:
- name: Retention Analysis
  description: Retention analysis operations
paths:
  /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
components:
  schemas:
    RetentionResult:
      type: object
      properties:
        data:
          type: object
          description: Retention data organized by cohort date with day-by-day return percentages.
  parameters:
    endDate:
      name: end
      in: query
      required: true
      description: The end date in YYYYMMDD format.
      schema:
        type: string
        pattern: ^\d{8}$
    startDate:
      name: start
      in: query
      required: true
      description: The start date in YYYYMMDD format.
      schema:
        type: string
        pattern: ^\d{8}$
  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.
externalDocs:
  description: Amplitude Dashboard REST API Documentation
  url: https://amplitude.com/docs/apis/analytics/dashboard-rest