openapi: 3.1.0
info:
  title: Amplitude Attribution Annotations Event Segmentation API
  description: The Amplitude Attribution API allows developers to send attribution campaign events to Amplitude from ad networks, attribution providers, or custom marketing tools. It associates users with the campaigns, channels, and creatives that drove their acquisition or re-engagement. This API is used to enrich Amplitude user profiles with marketing attribution data for campaign performance analysis and ROI measurement.
  version: '2'
  contact:
    name: Amplitude Support
    url: https://amplitude.com/contact
  termsOfService: https://amplitude.com/terms
servers:
- url: https://api2.amplitude.com
  description: Amplitude US Production Server
- url: https://api.eu.amplitude.com
  description: Amplitude EU Production Server
security: []
tags:
- name: Event Segmentation
  description: Event segmentation analysis operations
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
components:
  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
  parameters:
    endDate:
      name: end
      in: query
      required: true
      description: The end date in YYYYMMDD format.
      schema:
        type: string
        pattern: ^\d{8}$
    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}$
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution