QueryRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentanalytics-sh/json-schema/agentanalytics-sh-query-request-schema.json",
  "title": "QueryRequest",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/agentanalytics-sh-api-openapi.yml#/components/schemas/QueryRequest",
  "type": "object",
  "required": [
    "project"
  ],
  "properties": {
    "project": {
      "type": "string",
      "description": "Project name"
    },
    "metrics": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "event_count",
          "unique_users",
          "session_count",
          "bounce_rate",
          "avg_duration"
        ]
      },
      "default": [
        "event_count"
      ],
      "description": "Metrics to compute"
    },
    "group_by": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "event",
          "date",
          "user_id",
          "session_id",
          "country"
        ]
      },
      "default": [],
      "description": "Built-in fields to group results by. Property-based grouping such as `properties.hostname` is not supported."
    },
    "filters": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Field to filter on. Built-in: `event`, `user_id`, `date`, `country`, `session_id`, `timestamp`. You can also filter on any `properties.*` field, including first-touch attribution fields like `properties.first_utm_source`."
          },
          "op": {
            "type": "string",
            "enum": [
              "eq",
              "neq",
              "gt",
              "lt",
              "gte",
              "lte",
              "contains"
            ]
          },
          "value": {
            "description": "Value to compare against"
          }
        }
      }
    },
    "date_from": {
      "type": "string",
      "description": "Start date (ISO 8601 or `Nd` shorthand). Defaults to 7 days ago."
    },
    "date_to": {
      "type": "string",
      "description": "End date (ISO 8601). Defaults to today."
    },
    "count_mode": {
      "type": "string",
      "enum": [
        "raw",
        "session_then_user"
      ],
      "description": "How `event_count` is aggregated. Default for `event_count`: `session_then_user`. Session-backed rows count by session, no-session rows fall back to user only when that user has no session-backed row in the same group, and fully anonymous rows fall back to event id. Ignored for queries without `event_count`. Use `raw` to count ingested rows without dedupe."
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Optional raw email for authenticated lookup. Send only in the HTTPS POST body. The API normalizes it, computes a scoped HMAC lookup index server-side, and does not store raw email in event rows or profile traits."
    },
    "order_by": {
      "type": "string",
      "enum": [
        "event_count",
        "unique_users",
        "session_count",
        "date",
        "event"
      ],
      "description": "Field to sort by"
    },
    "order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc"
    },
    "limit": {
      "type": "integer",
      "default": 100,
      "maximum": 1000,
      "minimum": 1
    }
  }
}