> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gaintrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest metric events

> Ingests a batch of typed metric events into the metrics engine (feeds daily snapshots that calc metrics evaluate). Idempotent on `(source, externalId)`; duplicates are skipped silently. Returns a per-event outcome.

**Scope:** `write:events` · **1–500 events per request.**



## OpenAPI

````yaml /openapi.json post /metric-events
openapi: 3.1.0
info:
  title: GainTrace API
  version: 1.0.0
  description: >-
    The GainTrace REST API (v1). Read your customer data and push product-usage
    events, metric events, and signals into GainTrace.


    All endpoints are authenticated with a Bearer API key and scoped to a single
    workspace.
servers:
  - url: https://app.gaintrace.com/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Companies
    description: Read and manage canonical company records.
  - name: Signals
    description: Read, create, and manage buyer / risk signals.
  - name: Ingest
    description: Push product-usage and metric events into GainTrace.
  - name: Contacts
    description: Read and manage the people on an account.
  - name: Webhooks
    description: Subscribe to workspace events with signed, retried delivery.
paths:
  /metric-events:
    post:
      tags:
        - Ingest
      summary: Ingest metric events
      description: >-
        Ingests a batch of typed metric events into the metrics engine (feeds
        daily snapshots that calc metrics evaluate). Idempotent on `(source,
        externalId)`; duplicates are skipped silently. Returns a per-event
        outcome.


        **Scope:** `write:events` · **1–500 events per request.**
      operationId: ingestMetricEvents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricEventBatch'
      responses:
        '202':
          description: Batch processed. See `outcomes` for per-event status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  summary:
                    type: object
                    properties:
                      received:
                        type: integer
                      ingested:
                        type: integer
                      duplicate:
                        type: integer
                      rejected:
                        type: integer
                  outcomes:
                    type: array
                    items:
                      $ref: '#/components/schemas/MetricEventOutcome'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    MetricEventBatch:
      type: object
      required:
        - events
      properties:
        source:
          type: string
          enum:
            - script
            - api
            - segment
            - pendo
            - mixpanel
            - import
            - system
          default: api
        strict:
          type: boolean
          default: false
          description: >-
            When true, reject events whose `eventName` is not registered in
            event definitions.
        events:
          type: array
          minItems: 1
          maxItems: 500
          items:
            $ref: '#/components/schemas/MetricEvent'
    MetricEventOutcome:
      type: object
      properties:
        index:
          type: integer
        status:
          type: string
          enum:
            - ingested
            - duplicate
            - rejected
        error:
          type: string
        eventLogId:
          type: integer
    MetricEvent:
      type: object
      required:
        - eventName
        - occurredAt
      description: >-
        Provide exactly one company key (`companyId` OR `companyExternalId`).
        Contact attribution is optional.
      properties:
        companyId:
          type: string
          format: uuid
          description: Account UUID. Provide this or `companyExternalId`.
        companyExternalId:
          type: string
          description: >-
            Account slug/CRM id; resolves to a company. Provide this or
            `companyId`.
        enduserId:
          type: string
          format: uuid
        enduserEmail:
          type: string
          format: email
        eventName:
          type: string
          minLength: 1
          maxLength: 120
        occurredAt:
          type: string
          format: date-time
        properties:
          type: object
          additionalProperties: true
          description: Optionally shape-validated against the event definition.
        externalId:
          type: string
          maxLength: 200
          description: Idempotency key; repeats are skipped silently.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable, safe error message.
        detail:
          type: string
        code:
          type: string
      required:
        - error
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient scope, or API v1 is not enabled for the workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-key rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer API key. Secret server keys start with `gt_live_`; client-safe
        browser keys start with `gt_pub_` (write-only, origin-pinned). Create
        and scope keys in Settings → API Keys.

````