FunnelResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/agentanalytics-sh/json-schema/agentanalytics-sh-funnel-response-schema.json",
  "title": "FunnelResponse",
  "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/FunnelResponse",
  "type": "object",
  "properties": {
    "project_context": {
      "$ref": "#/$defs/ProjectContext"
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "step": {
            "type": "integer"
          },
          "event": {
            "type": "string"
          },
          "users": {
            "type": "integer",
            "description": "Number of users (or sessions) that reached this step"
          },
          "conversion_rate": {
            "type": "number",
            "description": "Fraction of users from previous step that reached this step (step 1 is always 1.0)"
          },
          "drop_off_rate": {
            "type": "number",
            "description": "Fraction of users lost from previous step (step 1 is always 0)"
          },
          "avg_time_to_next_ms": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average time in ms from this step to the next step (null for last step)"
          }
        }
      }
    },
    "overall_conversion_rate": {
      "type": "number",
      "description": "Fraction of step 1 users that completed the final step"
    },
    "breakdowns": {
      "type": "array",
      "description": "Per-group funnel results (only present when `breakdown` param is set). Ordered by step 1 users descending.",
      "items": {
        "type": "object",
        "properties": {
          "value": {
            "type": [
              "string",
              "null"
            ],
            "description": "Breakdown property value (null for events missing the property)"
          },
          "steps": {
            "type": "array",
            "description": "Same shape as top-level steps array",
            "items": {
              "type": "object",
              "properties": {
                "step": {
                  "type": "integer"
                },
                "event": {
                  "type": "string"
                },
                "users": {
                  "type": "integer"
                },
                "conversion_rate": {
                  "type": "number"
                },
                "drop_off_rate": {
                  "type": "number"
                },
                "avg_time_to_next_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              }
            }
          },
          "overall_conversion_rate": {
            "type": "number",
            "description": "End-to-end conversion for this group"
          }
        }
      }
    }
  },
  "$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."
        }
      }
    }
  }
}