Arkham Analytics API

openapi: 3.0.0
info:
  title: Arkham Intel Analytics API
  version: 1.1.0
tags:
- name: Analytics
paths:
  /analytics/credit-periods:
    get:
      summary: Get historical credit usage by billing period
      description: 'Returns the last 12 billing periods of credit usage for your billing entity.


        Each period includes the period boundaries, plan credits included, extra (overage) credits, and total credits consumed.


        Only available to organization admins (returning their org''s usage) and individual API subscribers (returning their own usage). Other callers receive `403`.'
      operationId: GetCreditPeriods
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CreditUsagePeriod'
                example:
                - computedAt: '2026-05-01T00:05:12Z'
                  creditsIncluded: 500000
                  creditsUsed: 482350
                  entityId: org_01HF8X3J0KQZ2N7T6P9YV4WB5R
                  entityType: org
                  extraCredits: 0
                  periodEnd: '2026-05-01T00:00:00Z'
                  periodStart: '2026-04-01T00:00:00Z'
                  status: closed
        '500':
          description: Internal Server Error
      tags:
      - Analytics
  /analytics/endpoint-calls:
    get:
      summary: Get API endpoint call analytics
      description: 'Returns your API usage broken down by endpoint, including call counts and credits consumed.


        If your API key belongs to an organization member, results are scoped to your usage within that org. Otherwise, results cover your individual subscription usage.'
      operationId: GetAnalyticsData
      parameters:
      - name: period
        in: query
        description: 'Time window: "24h", "7d", or "30d". Defaults to "24h". Ignored when both start_date and end_date are provided.'
        schema:
          enum:
          - 24h
          - 7d
          - 30d
          type: string
          description: 'Time window: "24h", "7d", or "30d". Defaults to "24h". Ignored when both start_date and end_date are provided.'
          example: 7d
      - name: end_date
        in: query
        description: RFC3339 timestamp. Historical cutoff for the period-based window, or the upper bound of a custom range.
        schema:
          type: string
          description: RFC3339 timestamp. Historical cutoff for the period-based window, or the upper bound of a custom range.
          example: '2026-05-26T00:00:00Z'
      - name: start_date
        in: query
        description: RFC3339 timestamp. Lower bound of a custom date range. Only takes effect together with end_date — a custom range requires both; start_date supplied on its own is ignored. Max range 366 days.
        schema:
          type: string
          description: RFC3339 timestamp. Lower bound of a custom date range. Only takes effect together with end_date — a custom range requires both; start_date supplied on its own is ignored. Max range 366 days.
          example: '2026-04-26T00:00:00Z'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
        '400':
          description: Bad Request
        '500':
          description: Internal Server Error
      tags:
      - Analytics
components:
  schemas:
    CreditUsagePeriod:
      required:
      - entityType
      - entityId
      - periodStart
      - periodEnd
      - creditsUsed
      - creditsIncluded
      - extraCredits
      - status
      - computedAt
      type: object
      properties:
        computedAt:
          type: string
          description: When this usage snapshot was computed.
          format: date-time
          example: '2026-05-01T00:05:12Z'
        creditsIncluded:
          type: integer
          description: Plan credits included in the period.
          example: 500000
        creditsUsed:
          type: integer
          description: Total credits consumed during the period.
          example: 482350
        entityId:
          type: string
          description: Identifier of the billing entity (org ID or Firebase UID).
          example: org_01HF8X3J0KQZ2N7T6P9YV4WB5R
        entityType:
          type: string
          description: 'Billing entity type: "org" or "individual".'
          example: org
        extraCredits:
          type: integer
          description: Overage credits purchased or accrued during the period.
          example: 0
        periodEnd:
          type: string
          description: Exclusive end of the billing period.
          format: date-time
          example: '2026-05-01T00:00:00Z'
        periodStart:
          type: string
          description: Inclusive start of the billing period.
          format: date-time
          example: '2026-04-01T00:00:00Z'
        status:
          type: string
          description: 'Period status: "current" or "closed".'
          example: closed
      example:
        computedAt: '2026-05-01T00:05:12Z'
        creditsIncluded: 500000
        creditsUsed: 482350
        entityId: org_01HF8X3J0KQZ2N7T6P9YV4WB5R
        entityType: org
        extraCredits: 0
        periodEnd: '2026-05-01T00:00:00Z'
        periodStart: '2026-04-01T00:00:00Z'
        status: closed
    EndpointInfo:
      required:
      - pattern
      - color
      - weight
      - unitType
      type: object
      properties:
        color:
          type: string
          description: Color used to render this endpoint in stacked-bar visualizations.
          example: '#4f46e5'
        pattern:
          type: string
          description: Endpoint path pattern.
          example: /transfers
        unitType:
          type: string
          description: 'Billing unit type: "call" (charged per request) or "row" (charged per returned row).'
          example: call
        weight:
          type: integer
          description: Credit weight per call for this endpoint.
          example: 5
      example:
        color: '#4f46e5'
        pattern: /transfers
        unitType: call
        weight: 5
    AnalyticsResponse:
      required:
      - period
      - startTime
      - endTime
      - dataPoints
      - endpointInfos
      type: object
      properties:
        dataPoints:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsDataPoint'
          description: Hourly data points covering the window.
          nullable: true
          example:
          - callBreakdown:
              /intelligence/address/{address}: 864
              /transfers: 420
            creditBreakdown:
              /intelligence/address/{address}: 5220
              /transfers: 2100
            hour: '2026-05-26T14:00:00Z'
            totalCalls: 1284
            totalCostUnits: 7320
            totalCredits: 7320
        endTime:
          type: string
          description: End of the returned window (UTC).
          format: date-time
          example: '2026-05-26T00:00:00Z'
        endpointInfos:
          type: array
          items:
            $ref: '#/components/schemas/EndpointInfo'
          description: Metadata for each endpoint referenced in the breakdowns (display color, credit weight, billing unit).
          nullable: true
          example:
          - color: '#4f46e5'
            pattern: /transfers
            unitType: call
            weight: 5
        period:
          type: string
          description: Time window the response covers. One of "24h", "7d", or "30d".
          example: 7d
        startTime:
          type: string
          description: Start of the returned window (UTC).
          format: date-time
          example: '2026-05-19T00:00:00Z'
      example:
        dataPoints:
        - callBreakdown:
            /intelligence/address/{address}: 864
            /transfers: 420
          creditBreakdown:
            /intelligence/address/{address}: 5220
            /transfers: 2100
          hour: '2026-05-26T14:00:00Z'
          totalCalls: 1284
          totalCostUnits: 7320
          totalCredits: 7320
        endTime: '2026-05-26T00:00:00Z'
        endpointInfos:
        - color: '#4f46e5'
          pattern: /transfers
          unitType: call
          weight: 5
        period: 7d
        startTime: '2026-05-19T00:00:00Z'
    AnalyticsDataPoint:
      required:
      - hour
      - totalCalls
      - totalCredits
      - totalCostUnits
      - callBreakdown
      - creditBreakdown
      type: object
      properties:
        callBreakdown:
          type: object
          additionalProperties:
            type: integer
          description: Per-endpoint call counts for this hour.
          nullable: true
          example:
            /intelligence/address/{address}: 864
            /transfers: 420
        creditBreakdown:
          type: object
          additionalProperties:
            type: integer
          description: Per-endpoint credits consumed for this hour.
          nullable: true
          example:
            /intelligence/address/{address}: 5220
            /transfers: 2100
        hour:
          type: string
          description: Bucket start time (UTC, truncated to the hour).
          format: date-time
          example: '2026-05-26T14:00:00Z'
        totalCalls:
          type: integer
          description: Total API calls made in this hour.
          example: 1284
        totalCostUnits:
          type: integer
          description: Total cost units in this hour (calls + row-billed units).
          example: 7320
        totalCredits:
          type: integer
          description: Total credits consumed in this hour.
          example: 7320
      example:
        callBreakdown:
          /intelligence/address/{address}: 864
          /transfers: 420
        creditBreakdown:
          /intelligence/address/{address}: 5220
          /transfers: 2100
        hour: '2026-05-26T14:00:00Z'
        totalCalls: 1284
        totalCostUnits: 7320
        totalCredits: 7320