Amplitude Ingestion API

openapi: 3.2.0
info:
  title: Amplitude Public Ingestion API
  version: '2026-10-05'
  summary: Event ingestion, analytics, taxonomy, export, async DSAR jobs, and agent-readable site content APIs for Amplitude.
  description: 'Amplitude is a digital analytics platform covering product analytics, experimentation, session replay, web analytics, and CDP capabilities.


    This document describes the public HTTP surface most useful to programmatic clients and AI agents:


    - **Ingestion** (`api2.amplitude.com`) — send events. Authenticated with a project API key in the request body.

    - **Analytics, Taxonomy, Export, Cohorts** (`amplitude.com/api`) — read and manage project data. Authenticated with HTTP Basic using a project API key and secret key.

    - **DSAR** (`amplitude.com/api/2/dsar`) — export a user’s data. Authenticated with HTTP Basic using the organization API key and organization secret key, not project credentials.

    - **Site content** (`amplitude.com`) — Markdown and index representations of amplitude.com pages, for retrieval-augmented and agent use.


    For conversational access to Amplitude data, prefer the Amplitude MCP server (`https://mcp.amplitude.com/mcp`, OAuth 2.0) over these REST APIs. For public documentation, use the read-only Docs MCP server (`https://amplitude.com/docs/api/mcp`).


    The full catalog of Amplitude’s agent-callable resources is published at https://amplitude.com/.well-known/ai-catalog.json.


    Endpoint coverage here is deliberately limited to documented, stable endpoints. See https://amplitude.com/docs/apis for the complete reference, including the Experiment, Attribution, Lookup Table, and User Privacy APIs.'
  termsOfService: https://amplitude.com/terms
  contact:
    name: Amplitude Support
    url: https://amplitude.com/support
  license:
    name: Amplitude Terms of Service
    url: https://amplitude.com/terms
servers:
- url: https://amplitude.com
  description: Analytics REST host (default / US data residency)
- url: https://analytics.eu.amplitude.com
  description: Analytics REST host (EU data residency)
tags:
- name: Ingestion
  description: Send event data to Amplitude.
  externalDocs:
    url: https://amplitude.com/docs/apis/analytics/http-v2
paths:
  /2/httpapi:
    x-replaces:
      path: /httpapi
      status: deprecated
      documentationUrl: https://amplitude.com/docs/apis/analytics/http-v2
    x-api-version: '2'
    servers:
    - url: https://api2.amplitude.com
      description: Event ingestion host (default / US data residency)
    - url: https://api.eu.amplitude.com
      description: Event ingestion host (EU data residency)
    post:
      tags:
      - Ingestion
      operationId: uploadEvents
      summary: Upload events (HTTP V2)
      description: 'Send events to Amplitude in real time. Requests are limited to 1 MB.


        **Retrying safely.** Idempotency is per event, not per request, and is keyed on `insert_id` — Amplitude does not honour an `Idempotency-Key` header. Set a stable `insert_id` on every event before the first attempt and reuse it verbatim on retries; Amplitude discards an event whose `insert_id` matches one already seen for that `device_id` within the last 7 days. Without it, a retry after a network timeout double-counts every event in the payload, because a request that timed out may still have been ingested.'
      security: []
      externalDocs:
        url: https://amplitude.com/docs/apis/analytics/http-v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRequestBody'
            example:
              api_key: YOUR_API_KEY
              events:
              - user_id: '12345'
                event_type: watch_tutorial
                time: 1396381378123
                event_properties:
                  source: notification
                user_properties:
                  Cohort: Test A
      responses:
        '200':
          description: Events accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSuccess'
        '400':
          $ref: '#/components/responses/IngestionBadRequest'
        '403':
          $ref: '#/components/responses/IngestionForbidden'
        '413':
          $ref: '#/components/responses/IngestionPayloadTooLarge'
        '429':
          $ref: '#/components/responses/IngestionRateLimited'
        '500':
          $ref: '#/components/responses/IngestionServerError'
  /batch:
    servers:
    - url: https://api2.amplitude.com
      description: Event ingestion host (default / US data residency)
    - url: https://api.eu.amplitude.com
      description: Event ingestion host (EU data residency)
    post:
      tags:
      - Ingestion
      operationId: uploadEventsBatch
      summary: Upload events (Batch)
      description: 'Upload large volumes of event data at once. Same payload shape as HTTP V2 with higher throughput limits and looser throttling. Use this for backfills and server-to-server pipelines.


        **Retrying safely.** As with HTTP V2, idempotency is keyed on each event’s `insert_id` rather than an `Idempotency-Key` header. Backfills are the case where this matters most: a retried batch without stable `insert_id` values silently duplicates every event it contains.'
      security: []
      externalDocs:
        url: https://amplitude.com/docs/apis/analytics/batch-event-upload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRequestBody'
      responses:
        '200':
          description: Events accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadSuccess'
        '400':
          $ref: '#/components/responses/IngestionBadRequest'
        '413':
          $ref: '#/components/responses/IngestionPayloadTooLarge'
        '429':
          $ref: '#/components/responses/IngestionRateLimited'
        '500':
          $ref: '#/components/responses/IngestionServerError'
components:
  responses:
    IngestionServerError:
      description: Server error. Retry the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    IngestionRateLimited:
      description: Too many requests for a user or device. Pause sending for that user or device for 30 seconds, then retry until the 429 clears.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 429
            error: Too many requests for some devices and users
    IngestionBadRequest:
      description: 'Invalid upload request: malformed JSON, missing required fields, invalid field values, or silenced devices.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 400
            error: Request missing required field
            missing_field: api_key
            events_with_missing_fields:
              event_type:
              - 3
    IngestionPayloadTooLarge:
      description: Payload exceeds 1 MB. Split the events array across multiple requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 413
            error: Payload too large
    IngestionForbidden:
      description: Blocked by Amplitude’s web application firewall, or sent from a sanctioned region.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 403
            error: Forbidden
  schemas:
    Event:
      type: object
      description: One of `user_id` or `device_id` is required, in addition to `event_type`.
      required:
      - event_type
      properties:
        event_type:
          type: string
          description: Unique identifier for the event. `$identify` and `$groupidentify` are reserved for identification.
        user_id:
          type: string
          description: ID for the user. Minimum 5 characters unless overridden with `min_id_length`.
          minLength: 5
        device_id:
          type: string
          description: Device-specific identifier.
        time:
          type: integer
          description: Event timestamp in milliseconds since epoch. Defaults to upload time.
        event_properties:
          type: object
          description: Data sent along with the event. Max depth 40.
        user_properties:
          type: object
          description: Data tied to the user. Supports `$set`, `$setOnce`, `$add`, `$append`, and `$unset` when `event_type` is `$identify`.
        groups:
          type: object
          description: Event-level groups. Requires the Accounts add-on. Up to 5 group types and 10 group values per event.
        group_properties:
          type: object
          description: Properties tied to the groups in `groups`. Applies when `event_type` is `$groupidentify`.
        insert_id:
          type: string
          description: Idempotency key for this event. Amplitude discards an event whose `insert_id` matches one already received for the same `device_id` within the last 7 days. Generate it before the first send — deterministically from the event, or as a UUID stored with it — and reuse the same value on every retry. Generating a fresh one per attempt defeats deduplication entirely.
        session_id:
          type: integer
          description: Session start time in milliseconds since epoch. `-1` means no session.
        event_id:
          type: integer
          description: Incrementing counter that distinguishes events with the same user and timestamp.
        app_version:
          type: string
        platform:
          type: string
        os_name:
          type: string
        os_version:
          type: string
        device_brand:
          type: string
        device_manufacturer:
          type: string
        device_model:
          type: string
        carrier:
          type: string
        country:
          type: string
        region:
          type: string
        city:
          type: string
        dma:
          type: string
        language:
          type: string
        location_lat:
          type: number
        location_lng:
          type: number
        ip:
          type: string
          description: IP address of the user. Use `$remote` to use the request IP.
        user_agent:
          type: string
          description: Unparsed user agent string, which Amplitude parses into user properties.
        price:
          type: number
        quantity:
          type: integer
        revenue:
          type: number
          description: Revenue amount. When price and quantity are both sent, revenue is price × quantity.
        productId:
          type: string
        revenueType:
          type: string
        currency:
          type: string
          description: Three-character uppercase ISO 4217 code.
        idfa:
          type: string
        idfv:
          type: string
        adid:
          type: string
        android_id:
          type: string
        android_app_set_id:
          type: string
        plan:
          type: object
          description: Tracking plan metadata.
          properties:
            branch:
              type: string
            source:
              type: string
            version:
              type: string
    UploadSuccess:
      type: object
      properties:
        code:
          type: integer
          const: 200
        events_ingested:
          type: integer
          description: Number of events ingested from the request.
        payload_size_bytes:
          type: integer
          description: Size of the upload payload in bytes.
        server_upload_time:
          type: integer
          description: Milliseconds since epoch when Amplitude accepted the request.
    UploadRequestBody:
      type: object
      required:
      - api_key
      - events
      properties:
        api_key:
          type: string
          description: Amplitude project API key.
        events:
          type: array
          description: Events to upload.
          items:
            $ref: '#/components/schemas/Event'
        options:
          type: object
          properties:
            min_id_length:
              type: integer
              description: Overrides the default minimum length of 5 for `user_id` and `device_id`.
    ApiError:
      type:
      - object
      - string
      description: Shared description of existing error bodies, not a new wire envelope. JSON APIs may return optional code/error fields or an errors array; other endpoints return text or Markdown. Fields are optional and clients must use the HTTP status and Content-Type. Endpoint-specific details may be present.
      properties:
        code:
          type: integer
          description: HTTP status code, repeated in the body.
        error:
          type: string
          description: Human-readable error description.
          examples:
          - Invalid request path
          - Missing request body
          - Invalid JSON request body
          - Request missing required field
          - Invalid event JSON
          - Invalid API key
          - Invalid field values on some events
        missing_field:
          type: string
          description: Request-level required field that is missing.
        events_with_invalid_fields:
          type: object
          description: Maps field names to the indexes of the events that failed validation.
        events_with_missing_fields:
          type: object
          description: Maps field names to the indexes of the events missing them.
        eps_threshold:
          type: integer
          description: Current events-per-second threshold for the project.
        throttled_devices:
          type: object
          description: Maps device IDs to their current events-per-second rate.
        throttled_events:
          type: array
          items:
            type: integer
          description: Indexes of events that were throttled.
        silenced_devices:
          type: array
          items:
            type: string
          description: Device IDs Amplitude has silenced.
        silenced_events:
          type: array
          items:
            type: integer
          description: Indexes of events whose device was silenced.
        exceeded_daily_quota_devices:
          type: object
          description: Maps device or user IDs to their daily event count, for those over quota.
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            additionalProperties: true
          description: Taxonomy API error details.
      additionalProperties: true
  securitySchemes:
    orgApiKeyAndSecretKey:
      type: http
      scheme: basic
      description: DSAR uses HTTP Basic with the org API key and org secret key, as documented in the DSAR request examples.
    apiKeyAndSecretKey:
      type: http
      scheme: basic
      description: 'HTTP Basic authentication. Username is the project API key, password is the project secret key. Both are found in Amplitude under Settings → Projects → General. Credentials must be base64 encoded.


        This scheme is project-scoped and all-or-nothing: a key pair grants every operation on its project. There is no narrower grant. When an agent needs least-privilege access, prefer the MCP server and its `mcpOAuth` scopes over these keys.'
    mcpOAuth:
      type: oauth2
      description: 'OAuth 2.1 authorization code flow with PKCE, used by the Amplitude MCP server at `https://mcp.amplitude.com/mcp`.


        Endpoints and scopes here mirror the authorization server metadata at https://mcp.amplitude.com/.well-known/oauth-authorization-server, which is authoritative. Clients may be registered dynamically (RFC 7591) at `https://mcp.amplitude.com/register`; public clients are supported.


        Scopes bound the token but do not widen it — every call is additionally enforced against the permissions of the Amplitude user who approved the grant. Request the narrowest scope that covers the task.


        For EU data residency, substitute `https://mcp.eu.amplitude.com`.'
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.amplitude.com/authorize
          tokenUrl: https://mcp.amplitude.com/token
          refreshUrl: https://mcp.amplitude.com/token
          scopes:
            mcp:read: Read charts, dashboards, cohorts, experiments, feature flags, events, properties, and session replays.
            mcp:write: Create and modify dashboards, notebooks, experiments, cohorts, and metrics.
            offline_access: Issue a refresh token so the agent can act after the user closes the browser. Omit for one-shot interactive tasks.
externalDocs:
  description: Amplitude API reference
  url: https://amplitude.com/docs/apis
x-api-versioning:
  scheme: per-api-path
  documentVersionScheme: date
  description: API families use independent path namespaces (for example /2/httpapi, /api/2/dsar and /api/5/cohorts). Batch and site-content paths are unversioned. The namespace number is not a shared release number or a semantic-version guarantee.
  deprecationPolicy:
    status: not-verified
    description: No company-wide REST retirement notice period or sunset dates are asserted by this document. SDK maintenance policy does not establish REST API lifecycle policy.