Paid analyticsExperimental API

openapi: 3.1.0
info:
  title: API Reference agents analyticsExperimental API
  version: 1.0.0
servers:
- url: https://api.agentpaid.io/api/v1
  description: Production
tags:
- name: analyticsExperimental
paths:
  /experimental/analytics/query:
    post:
      operationId: execute-analytics-query
      summary: Execute a SQL query against your analytics data (experimental)
      description: '⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.


        Runs a single ClickHouse SELECT (or WITH … SELECT) against your organization''s analytics views. Before writing a query, call `getAnalyticsSchema` (GET /schema) for the available views and columns, and `getSignalsMetadata` (GET /signals/metadata) for the JSON paths inside `fact_signal.data`. Results are automatically scoped to your organization — no org filter is needed or possible. Only SELECT/WITH statements are accepted.


        Conventions: monetary amounts are minor units (cents — divide by 100 for the major unit); most are integers, but `fact_cost.cost_amount` is fractional cents (Decimal) since a single AI call usually costs less than a cent; 64-bit integers (counts, ids, amounts) are returned as JSON strings to preserve precision, so parse them client-side. Query signal payloads via JSON paths, e.g. `SELECT data.country::String AS country, count() FROM fact_signal GROUP BY country`.


        Limits: 30 seconds of execution time and 10,000 result rows (truncation is flagged via `meta.truncated`). Prefer aggregates and a `created_at` date filter on large tables — this endpoint is for interactive analytics, not bulk export.'
      tags:
      - analyticsExperimental
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsQueryResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '408':
          description: '408'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: '429'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsQueryRequest'
  /experimental/analytics/schema:
    get:
      operationId: get-analytics-schema
      summary: List queryable analytics views, columns, and types (experimental)
      description: '⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.


        Returns the analytics views available to POST /query, with column names, ClickHouse types, and descriptions. Dimensions (`dim_*`) describe entities; facts (`fact_*`) are event/transaction tables that join to dimensions via the `*_id` columns described in each comment.'
      tags:
      - analyticsExperimental
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSchemaResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /experimental/analytics/signals/metadata:
    get:
      operationId: get-signals-metadata
      summary: Discover metadata keys present in your signals (experimental)
      description: '⚠️ **Experimental** — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.


        Lists the JSON paths (and their observed types) present in the `data` payload of your signals within a time window (default: last 30 days), grouped by signal name. Use the returned paths in queries against `fact_signal`, e.g. `WHERE data.<path>::String = ''...''`.'
      tags:
      - analyticsExperimental
      parameters:
      - name: signalName
        in: query
        description: Restrict discovery to a single signal name.
        required: false
        schema:
          type: string
      - name: fromDate
        in: query
        description: Start of the discovery window. Defaults to 30 days ago.
        required: false
        schema:
          type: string
          format: date-time
      - name: toDate
        in: query
        description: End of the discovery window. Defaults to now.
        required: false
        schema:
          type: string
          format: date-time
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignalsMetadataResponse'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AnalyticsColumn:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          description: ClickHouse column type
      required:
      - name
      - type
      title: AnalyticsColumn
    SignalsMetadataResponseSignalsItemsPathsItems:
      type: object
      properties:
        path:
          type: string
          description: JSON path inside the signal `data` payload, usable in queries as e.g. `data.<path>::String`.
        types:
          type: array
          items:
            type: string
          description: ClickHouse dynamic types observed for this path.
      required:
      - path
      - types
      title: SignalsMetadataResponseSignalsItemsPathsItems
    SignalsMetadataResponseMeta:
      type: object
      properties:
        fromDate:
          type: string
        toDate:
          type: string
      required:
      - fromDate
      - toDate
      title: SignalsMetadataResponseMeta
    SignalsMetadataResponseSignalsItems:
      type: object
      properties:
        signalName:
          type: string
        paths:
          type: array
          items:
            $ref: '#/components/schemas/SignalsMetadataResponseSignalsItemsPathsItems'
      required:
      - signalName
      - paths
      title: SignalsMetadataResponseSignalsItems
    AnalyticsQueryResponseMeta:
      type: object
      properties:
        rowCount:
          type: integer
        elapsedMs:
          type: number
          format: double
        truncated:
          type: boolean
          description: True when the result hit the row cap and was truncated. Narrow the query (shorter date range, LIMIT, coarser grouping) to see the rest.
      required:
      - rowCount
      - elapsedMs
      - truncated
      title: AnalyticsQueryResponseMeta
    AnalyticsQueryRequest:
      type: object
      properties:
        query:
          type: string
          description: A single ClickHouse SELECT (or WITH ... SELECT) statement against the analytics views. Results are automatically scoped to your organization. See GET /schema for the available views and columns.
      required:
      - query
      title: AnalyticsQueryRequest
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: string
      required:
      - error
      title: ErrorResponse
    AnalyticsSchemaColumn:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          description: ClickHouse column type
        comment:
          type: string
      required:
      - name
      - type
      - comment
      title: AnalyticsSchemaColumn
    SignalsMetadataResponse:
      type: object
      properties:
        signals:
          type: array
          items:
            $ref: '#/components/schemas/SignalsMetadataResponseSignalsItems'
        meta:
          $ref: '#/components/schemas/SignalsMetadataResponseMeta'
      required:
      - signals
      - meta
      title: SignalsMetadataResponse
    AnalyticsSchemaResponse:
      type: object
      properties:
        views:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsSchemaView'
      required:
      - views
      title: AnalyticsSchemaResponse
    AnalyticsSchemaView:
      type: object
      properties:
        name:
          type: string
        comment:
          type: string
        columns:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsSchemaColumn'
      required:
      - name
      - comment
      - columns
      title: AnalyticsSchemaView
    AnalyticsQueryResponse:
      type: object
      properties:
        columns:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsColumn'
        rows:
          type: array
          items:
            type: array
            items:
              description: Any type
          description: Result rows; values are ordered to match `columns`. 64-bit integers (UInt64/Int64 — counts, sums, amounts in cents, ids) are returned as JSON strings to preserve precision; parse them client-side as needed.
        meta:
          $ref: '#/components/schemas/AnalyticsQueryResponseMeta'
      required:
      - columns
      - rows
      - meta
      title: AnalyticsQueryResponse
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer