{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentanalytics-sh/json-schema/agentanalytics-sh-stats-response-schema.json",
  "title": "StatsResponse",
  "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/StatsResponse",
  "type": "object",
  "properties": {
    "project": {
      "type": "string"
    },
    "project_context": {
      "$ref": "#/$defs/ProjectContext"
    },
    "period": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        },
        "groupBy": {
          "type": "string",
          "enum": [
            "hour",
            "day",
            "week",
            "month"
          ]
        }
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "unique_users": {
          "type": "integer"
        },
        "total_events": {
          "type": "integer"
        }
      }
    },
    "timeSeries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "bucket": {
            "type": "string"
          },
          "unique_users": {
            "type": "integer"
          },
          "total_events": {
            "type": "integer"
          }
        }
      }
    },
    "events": {
      "type": "array",
      "description": "Top event names by count (max 20)",
      "items": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "unique_users": {
            "type": "integer"
          }
        }
      }
    },
    "countries": {
      "type": "array",
      "description": "Country groups sorted by raw event count for the same project and period as totals.\nEvent counts sum to totals.total_events. Users may appear in multiple countries,\nso country unique-user counts are not additive. Missing/empty country, XX,\nand T1 are grouped as null (Unknown in CLI and MCP).\n",
      "items": {
        "type": "object",
        "required": [
          "country",
          "count",
          "unique_users"
        ],
        "properties": {
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "unique_users": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    },
    "sessions": {
      "type": "object",
      "properties": {
        "total_sessions": {
          "type": "integer"
        },
        "bounce_rate": {
          "type": "number",
          "description": "Bounce rate computed from event names at query time.\nA session is a bounce when it has only non-interactive events:\n`page_view`, `$impression`, `$scroll_depth`, `$error`, `$time_on_page`, `$performance`, `$web_vitals`.\n"
        },
        "avg_duration": {
          "type": "integer",
          "description": "Average session duration in milliseconds"
        },
        "pages_per_session": {
          "type": "number"
        },
        "sessions_per_user": {
          "type": "number"
        }
      }
    }
  },
  "$defs": {
    "ProjectContext": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "goals": {
          "type": "array",
          "maxItems": 5,
          "items": {
            "type": "string",
            "maxLength": 160
          },
          "default": []
        },
        "activation_events": {
          "type": "array",
          "maxItems": 8,
          "items": {
            "type": "string",
            "maxLength": 96
          },
          "default": [],
          "description": "Event names that define activation or the main success path."
        },
        "glossary": {
          "type": "array",
          "maxItems": 10,
          "items": {
            "$ref": "#/$defs/ProjectContextGlossaryEntry"
          },
          "default": []
        },
        "annotations": {
          "type": "array",
          "maxItems": 100,
          "items": {
            "$ref": "#/$defs/ProjectContextAnnotation"
          },
          "default": [],
          "description": "Major date annotations. Project-scoped analytics responses include only annotations inside the requested date range plus one day before and after."
        }
      }
    },
    "ProjectContextAnnotation": {
      "type": "object",
      "required": [
        "occurred_at",
        "title"
      ],
      "additionalProperties": false,
      "properties": {
        "occurred_at": {
          "type": "string",
          "format": "date-time",
          "description": "ISO-8601 datetime when a major product change happened. Stored as a UTC ISO string."
        },
        "title": {
          "type": "string",
          "maxLength": 120,
          "description": "Short annotation title for a meaningful product, pricing, release, landing-page, onboarding, feature, or experiment change."
        },
        "note": {
          "type": "string",
          "maxLength": 500,
          "description": "Optional short note. Do not store commit logs, PII, secrets, or long release notes."
        }
      }
    },
    "ProjectContextGlossaryEntry": {
      "type": "object",
      "required": [
        "event_name",
        "term",
        "definition"
      ],
      "properties": {
        "event_name": {
          "type": "string",
          "maxLength": 96,
          "description": "Event name this glossary entry explains. Use `/properties` or `/properties/received` to inspect current project event names before updating."
        },
        "term": {
          "type": "string",
          "maxLength": 64,
          "description": "Human or product term for the event."
        },
        "definition": {
          "type": "string",
          "maxLength": 240,
          "description": "Short meaning that helps an agent interpret analytics results."
        }
      }
    }
  }
}