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

# Submit a numerical or registered-metric forecast

> Requires forecast:submit. Retain the original payload and Idempotency-Key for uncertain retries. Request body limit: 1 MiB.



## OpenAPI

````yaml /api-reference/forecasting/openapi.json post /api/forecasts
openapi: 3.1.0
info:
  title: Mach-1 forecasting API
  version: 2026-10
  description: >-
    Bounded forecasting using the existing prediction engine. Requires
    forecast-scoped credentials. Numerical limits: 4 series, 32768 total history
    buckets, 10000 total future points, 8 drivers per series. Runtime
    normalization additionally checks alignment, timezone, and observed-history
    rules.
servers:
  - url: https://build.aioncx.com
security:
  - forecastKey: []
paths:
  /api/forecasts:
    post:
      summary: Submit a numerical or registered-metric forecast
      description: >-
        Requires forecast:submit. Retain the original payload and
        Idempotency-Key for uncertain retries. Request body limit: 1 MiB.
      operationId: submitMach1Forecast
      parameters:
        - name: workspace_id
          in: query
          required: false
          description: >-
            Select a granted workspace. Required when a credential grants
            multiple workspaces.
          schema:
            type: string
            format: uuid
        - name: Idempotency-Key
          in: header
          required: true
          description: Stable caller-generated key. Reuse only with the same request.
          schema:
            type: string
            minLength: 1
            maxLength: 256
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForecastRequest'
            example:
              method: auto
              source:
                type: numerical
                grain: day
                timezone: UTC
                historyStart: '2026-01-01T00:00:00Z'
                horizon: 4
                series:
                  - id: daily-contacts
                    values:
                      - 42
                      - 45
                      - 48
                      - 43
                      - 51
                      - 36
                      - 31
                      - 44
                      - 47
                      - 50
                      - 46
                      - 54
                      - 38
                      - 33
                      - 46
                      - 49
                      - 52
                      - 48
                      - 56
                      - 40
                      - 35
                      - 48
                      - 51
                      - 54
                      - 50
                      - 58
                      - 42
                      - 37
      responses:
        '200':
          description: Existing or immediately resolved run
          content:
            application/json:
              schema:
                type: object
                required:
                  - run_id
                  - status
                  - results_url
                properties:
                  run_id:
                    type: string
                    format: uuid
                  status:
                    type: string
                  results_url:
                    type: string
                  price:
                    type: object
                    additionalProperties: true
                    description: >-
                      Price retained at first acceptance. See the guide for
                      current forecasting charges.
        '202':
          description: Accepted; draft, queued, or running
          content:
            application/json:
              schema:
                type: object
                required:
                  - run_id
                  - status
                  - results_url
                properties:
                  run_id:
                    type: string
                    format: uuid
                  status:
                    type: string
                  results_url:
                    type: string
                  price:
                    type: object
                    additionalProperties: true
                    description: >-
                      Price retained at first acceptance. See the guide for
                      current forecasting charges.
        '400':
          description: Request refused or service unavailable
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  retryable:
                    type: boolean
        '401':
          description: Request refused or service unavailable
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  retryable:
                    type: boolean
        '403':
          description: Request refused or service unavailable
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  retryable:
                    type: boolean
        '404':
          description: Request refused or service unavailable
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  retryable:
                    type: boolean
        '409':
          description: Request refused or service unavailable
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  retryable:
                    type: boolean
        '413':
          description: Request refused or service unavailable
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  retryable:
                    type: boolean
        '415':
          description: Request refused or service unavailable
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  retryable:
                    type: boolean
        '503':
          description: Request refused or service unavailable
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                  retryable:
                    type: boolean
components:
  schemas:
    ForecastRequest:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        method:
          default: auto
          type: string
          enum:
            - timestral
            - auto
            - moving_average
            - weighted_recent_average
            - seasonal_baseline
            - seasonal_naive
            - holt_winters
            - driver_regression
        source:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  const: numerical
                grain:
                  type: string
                  enum:
                    - 15m
                    - 30m
                    - hour
                    - day
                    - week
                timezone:
                  default: UTC
                  type: string
                  maxLength: 64
                historyStart:
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                horizon:
                  type: integer
                  minimum: 1
                  maximum: 10000
                series:
                  minItems: 1
                  maxItems: 4
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                        maxLength: 120
                      values:
                        minItems: 2
                        maxItems: 32768
                        type: array
                        items:
                          anyOf:
                            - type: number
                            - type: 'null'
                      drivers:
                        maxItems: 8
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              minLength: 1
                              maxLength: 120
                            valueType:
                              type: string
                              enum:
                                - numeric
                                - categorical
                            availability:
                              type: string
                              enum:
                                - past_only
                                - known_future
                            required:
                              default: false
                              type: boolean
                            values:
                              type: array
                              items:
                                anyOf:
                                  - type: number
                                  - type: string
                                    maxLength: 120
                                  - type: 'null'
                            mask:
                              type: array
                              items:
                                type: boolean
                            availableAt:
                              type: array
                              items:
                                type: string
                                format: date-time
                                pattern: >-
                                  ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          required:
                            - id
                            - valueType
                            - availability
                            - values
                            - mask
                          additionalProperties: false
                    required:
                      - id
                      - values
                    additionalProperties: false
              required:
                - type
                - grain
                - historyStart
                - horizon
                - series
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  const: metric
                targetObjectType:
                  type: string
                  minLength: 1
                  maxLength: 120
                targetObjectId:
                  default: null
                  anyOf:
                    - type: string
                      maxLength: 240
                    - type: 'null'
                metricRef:
                  type: string
                  minLength: 1
                  maxLength: 240
                grain:
                  type: string
                  enum:
                    - 15m
                    - 30m
                    - hour
                    - day
                    - week
                timezone:
                  default: UTC
                  type: string
                  maxLength: 64
                historyStart:
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                historyEnd:
                  type: string
                  format: date-time
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                horizon:
                  type: integer
                  minimum: 1
                  maximum: 10000
                dimensions:
                  default: []
                  maxItems: 4
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 120
                filters:
                  default: []
                  anyOf:
                    - type: array
                      items:
                        type: object
                        properties:
                          targetType:
                            type: string
                            enum:
                              - object
                              - attribute
                              - metric
                              - time
                          ref:
                            type: string
                            minLength: 1
                          operator:
                            type: string
                            enum:
                              - eq
                              - neq
                              - in
                              - not_in
                              - gt
                              - gte
                              - lt
                              - lte
                              - between
                              - contains
                              - is_null
                              - is_not_null
                          value:
                            anyOf:
                              - anyOf:
                                  - type: string
                                  - type: number
                                  - type: boolean
                              - type: array
                                items:
                                  anyOf:
                                    - type: string
                                    - type: number
                                    - type: boolean
                              - type: 'null'
                        required:
                          - targetType
                          - ref
                          - operator
                        additionalProperties: false
                    - type: object
                      propertyNames:
                        type: string
                        minLength: 1
                      additionalProperties:
                        anyOf:
                          - anyOf:
                              - type: string
                              - type: number
                              - type: boolean
                          - type: array
                            items:
                              anyOf:
                                - type: string
                                - type: number
                                - type: boolean
                          - type: 'null'
                inputs:
                  default: []
                  maxItems: 8
                  type: array
                  items:
                    type: object
                    properties:
                      semanticRef:
                        type: string
                        minLength: 1
                        maxLength: 240
                      kind:
                        default: metric
                        type: string
                        const: metric
                      role:
                        default: feature
                        type: string
                        const: feature
                      lagPeriods:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      label:
                        anyOf:
                          - type: string
                            maxLength: 200
                          - type: 'null'
                    required:
                      - semanticRef
                timeRole:
                  type: string
                  minLength: 1
                  maxLength: 120
                scopeTime:
                  default:
                    mode: event_time
                  oneOf:
                    - type: object
                      properties:
                        mode:
                          type: string
                          const: event_time
                      required:
                        - mode
                      additionalProperties: false
                    - type: object
                      properties:
                        mode:
                          type: string
                          const: reconstruction
                        effectiveAt:
                          type: string
                          format: date-time
                          pattern: >-
                            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                      required:
                        - mode
                        - effectiveAt
                      additionalProperties: false
              required:
                - type
                - targetObjectType
                - metricRef
                - grain
                - historyStart
                - historyEnd
                - horizon
              additionalProperties: false
      required:
        - source
      additionalProperties: false
  securitySchemes:
    forecastKey:
      type: http
      scheme: bearer
      description: >-
        A scoped Mach-1 atlas_ingest_ key with forecast:submit and/or
        forecast:read. Ingestion scopes alone do not grant forecasting.

````

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