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

# Ingest business metric datapoints

> Submit one or more datapoints for a customer-defined business metric. Returns 202 when the payload is valid and queued for processing.

Requires an API key with the **metrics:ingest** scope. Create metric definitions in the Optimaze dashboard before calling this endpoint. See Authentication in the API tab for key setup.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/metrics/ingest
openapi: 3.1.0
info:
  title: Optimaze API
  description: >-
    Programmatic access to the Optimaze platform. This specification is the
    single source of truth for public HTTP APIs and grows as new endpoints ship.
    Use API keys with scoped permissions to integrate billing, business metrics,
    and platform data into your systems.
  version: 1.0.0
servers:
  - url: https://api.optimazehq.com
security: []
tags:
  - name: Business metrics
    description: >-
      Ingest customer-defined business metric datapoints — revenue, usage, KPIs,
      and other signals — for unit economics and attribution.
  - name: Integrations
    description: >-
      Query and manage cloud, AI, and finance integrations. Endpoints will be
      added as programmatic integration management becomes available.
  - name: Reporting
    description: >-
      Read attribution, cost, and unit economics data. Endpoints will be added
      as read APIs for dashboards and downstream systems ship.
paths:
  /v1/metrics/ingest:
    post:
      tags:
        - Business metrics
      summary: Ingest business metric datapoints
      description: >-
        Submit one or more datapoints for a customer-defined business metric.
        Returns 202 when the payload is valid and queued for processing.


        Requires an API key with the **metrics:ingest** scope. Create metric
        definitions in the Optimaze dashboard before calling this endpoint. See
        Authentication in the API tab for key setup.
      operationId: ingestBusinessMetricDatapoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricsIngestRequest'
            examples:
              singleDatapoint:
                summary: Single revenue datapoint
                value:
                  metric_id: '123456789'
                  source: finance-warehouse
                  sample_rate: 1
                  data:
                    - event_time: '2026-01-31T23:59:59Z'
                      value: 48250
                      tags:
                        currency: AUD
                        plan: enterprise
              batchDatapoints:
                summary: Multiple datapoints with dimensions
                value:
                  metric_id: '123456789'
                  source: billing-system
                  data:
                    - event_time: '2026-01-15T10:30:00Z'
                      value: 125000.5
                      tags:
                        region: ap-southeast-2
                        plan: enterprise
                    - event_time: '2026-01-15T11:30:00Z'
                      value: 126100.25
                      tags:
                        region: ap-southeast-2
                        plan: enterprise
      responses:
        '202':
          description: Datapoints accepted and queued for processing
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '403':
          description: API key lacks metrics:ingest scope or organisation mismatch
      security:
        - optimazeApiKey: []
          optimazeOrgId: []
components:
  schemas:
    MetricsIngestRequest:
      type: object
      required:
        - metric_id
        - data
      properties:
        metric_id:
          type: string
          description: Customer metric ID defined in the Optimaze dashboard.
        source:
          type: string
          description: Originating system identifier. Defaults to ingest-api when omitted.
        sample_rate:
          type: number
          minimum: 0
          maximum: 1
          description: Sampling rate between 0 and 1. Defaults to 1.0.
        data:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/MetricDataPoint'
    Error:
      type: object
      properties:
        message:
          type: string
    MetricDataPoint:
      type: object
      required:
        - event_time
        - value
      properties:
        event_time:
          type: string
          format: date-time
          description: RFC3339 timestamp when the observation occurred.
        value:
          type: number
          description: Numeric metric value.
        tags:
          type: object
          additionalProperties:
            type: string
          description: Optional key-value dimensions (for example region or product line).
  securitySchemes:
    optimazeApiKey:
      type: apiKey
      in: header
      name: optimaze-api-key
      description: >-
        Raw Optimaze API key (format omz_...). Created in the dashboard with the
        required scopes.
    optimazeOrgId:
      type: apiKey
      in: header
      name: optimaze-org-id
      description: Optimaze organisation ID for the integration.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.