AIXBT Metrics API

openapi: 3.2.0
info:
  title: AIXBT Public Metrics API
  version: 2.0.0
  description: 'Documentation for the AIXBT public API (v2).


    Most endpoints require an API key via the `x-api-key` header. Current topics, the deprecated `/grounding` topics alias, and cluster, category, and chain metadata are public. Historical topic data and all project, intel, signal, and recipe endpoints require authentication.


    Self-serve accounts can retrieve a rolling 90 days of proprietary AIXBT history, reported in `meta.history`. The boundary applies to explicit date ranges, historical `at` snapshots, pagination, and by-ID retrieval; older requests return `403 HISTORY_WINDOW_EXCEEDED` with the same `meta.history`. Accounts with the `archive-history` entitlement are uncapped. Current Topics and published Reports are excluded, while price candles and project market metrics retain their endpoint-specific windows.


    For full usage instructions, authentication and example projects, visit the documentation: docs.aixbt.tech.'
security:
- ApiKeyAuth: []
tags:
- name: Metrics
paths:
  /v2/projects/{id}/metrics:
    get:
      summary: Project Metrics Snapshot
      tags:
      - Metrics
      description: 'Point-in-time snapshot of project market metrics (price, volume, 24h change,

        derived fields like price-change-7d/14d/30d and ATH change percentage).


        Without `at`, returns the live metrics subdocument from the project record

        (sourced from CoinGecko by the metrics sync).


        With `at`, reads from Timescale `metric_log` (latest row ≤ `at` within a 2-hour

        lookback) and recomputes derived fields from `at - 7d / 14d / 30d` lookups.'
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: MongoDB ObjectId of the project
      - in: query
        name: at
        schema:
          type: string
          format: date-time
        description: 'Historical timestamp (ISO 8601). Returns project metrics as they existed

          at this point in time. Must be in the past.

          '
        example: 2026-03-25 12:00:00+00:00
      responses:
        '200':
          description: Project metrics snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  meta:
                    $ref: '#/components/schemas/UpgradeMeta'
                  data:
                    type: object
                    properties:
                      projectId:
                        type: string
                        example: 507f1f77bcf86cd799439011
                      projectName:
                        type: string
                        example: ethereum
                      metrics:
                        type: object
                        properties:
                          usd:
                            type: number
                          usdMarketCap:
                            type: number
                          usd24hVol:
                            type: number
                          usd24hChange:
                            type: number
                          lastUpdatedAt:
                            type: number
                            description: Unix timestamp (seconds)
                          high24h:
                            type: number
                          low24h:
                            type: number
                          athUsd:
                            type: number
                          athDate:
                            type: string
                            format: date-time
                          athChangePct:
                            type: number
                          priceChange7d:
                            type: number
                          priceChange14d:
                            type: number
                          priceChange30d:
                            type: number
        '400':
          description: Invalid project ID format or invalid `at` parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Authentication required. Provide an API key to access this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Project not found, token metrics are not available for an NFT collection, or no metrics are available at the requested timestamp
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Failed to fetch project metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Historical queries temporarily unavailable (TimescaleDB connectivity issue)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      operationId: getV2ProjectsByIdMetrics
components:
  schemas:
    Pagination:
      type: object
      required:
      - page
      - limit
      - totalCount
      - hasMore
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
        totalCount:
          type: integer
          minimum: 0
        hasMore:
          type: boolean
    ApiError:
      type: object
      required:
      - error
      description: Error response. Middleware may include additional rate-limit or access metadata.
      properties:
        error:
          type: string
        message:
          type: string
        code:
          type: string
        status:
          type: integer
        data: {}
        meta:
          type: object
          additionalProperties: true
        details:
          type: object
          additionalProperties: true
        pagination:
          $ref: '#/components/schemas/Pagination'
        limitType:
          type: string
          enum:
          - minute
          - day
          description: Rate-limit window that was exhausted.
        retryAfterMs:
          type: integer
          minimum: 0
          description: Milliseconds until the exhausted window resets.
        limits:
          type: object
          required:
          - minute
          - day
          properties:
            minute:
              $ref: '#/components/schemas/RateLimitWindow'
            day:
              $ref: '#/components/schemas/RateLimitWindow'
        issues:
          type: array
          items:
            type: object
            required:
            - path
            - message
            properties:
              path:
                type: string
              message:
                type: string
      additionalProperties: true
    UpgradeMeta:
      type: object
      description: Present on supported unauthenticated responses with an account access link.
      properties:
        upgrade:
          type: object
          properties:
            description:
              type: string
            url:
              type: string
              format: uri
              example: https://aixbt.tech/subscribe
    RateLimitWindow:
      type: object
      required:
      - limit
      - remaining
      - resetAt
      properties:
        limit:
          type: integer
          minimum: 0
        remaining:
          type: integer
          minimum: 0
        resetAt:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key to authorize requests