{ "openapi": "3.0.3", "info": { "title": "evstats OpenAPI", "version": "0.1.0", "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "description": "Read-only analytics API of evstats. Numbers are identical to the dashboard because both call the same query kernel and share one result cache.\n\nAuthentication: `Authorization: Bearer evs_...` with an API key created by a dashboard user. The key sees exactly the projects its user can see; revoking the user's access applies immediately. Project write keys (evs_wk_...) are rejected.\n\nEvery response is `{ \"code\": 0, \"message\": \"ok\", \"data\": ... }`; failures carry a non-zero code (see ErrorCode). Empty results are empty arrays, never 404.\n\nDates: `from` and `to` are YYYY-MM-DD in the project time zone and both inclusive. A week starts on Monday. Each module has a longest range (see its description).\n\nRate limit: 60 requests per minute per key across the whole cluster (42901 when exceeded). There is no CSV export, realtime, SQL or write access in this API." }, "servers": [ { "url": "/" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "projects" }, { "name": "analytics" } ], "paths": { "/api/v1/projects": { "get": { "tags": [ "projects" ], "operationId": "listProjects", "summary": "Projects visible to the key's user", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectList" } } } ] } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}": { "get": { "tags": [ "projects" ], "operationId": "getProject", "summary": "One project", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Project" } } } ] } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/attribution": { "get": { "tags": [ "analytics" ], "description": "Conversions credited to channels by first, last or linear touch. Longest range: 90 days.", "operationId": "attribution", "summary": "Attribution · 归因", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "conversion event", "name": "event", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "default": "first", "enum": [ "first", "last", "linear" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_attribution" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/event-names": { "get": { "tags": [ "analytics" ], "description": "Event names seen in the range with display names; use it to align event names. Longest range: 366 days.", "operationId": "event_names", "summary": "Event names · 事件名", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_event_names" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/events": { "get": { "tags": [ "analytics" ], "description": "Count, users and per-user count of each track event. Longest range: 366 days.", "operationId": "events", "summary": "Events · 事件统计", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "optional event name; returns its daily trend", "name": "event", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "include_hidden", "in": "query", "required": false, "schema": { "type": "string", "default": "0", "enum": [ "0", "1" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_events" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/events/logs": { "get": { "tags": [ "analytics" ], "description": "Individual events, newest first. Longest range: 31 days.", "operationId": "event_logs", "summary": "Event log · 事件日志", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "name": "event", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "distinct_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_event_logs" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/experiments": { "get": { "tags": [ "analytics" ], "description": "A/B experiments with status and entered users. Longest range: 90 days.", "operationId": "experiments", "summary": "Experiments · 实验列表", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_experiments" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/experiments/{experimentId}": { "get": { "tags": [ "analytics" ], "description": "Per-variant entered users, converted users, rate and z-test conclusion. Longest range: 90 days.", "operationId": "experiment", "summary": "Experiment · 实验结果", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "experimentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_experiment" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/explore": { "get": { "tags": [ "analytics" ], "description": "One event, count or users, grouped by one fixed dimension or property over time. Longest range: 31 days.", "operationId": "explore", "summary": "Explore · 自定义分析", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "name": "event", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "measure", "in": "query", "required": false, "schema": { "type": "string", "default": "count", "enum": [ "count", "users" ] } }, { "name": "dim", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "url_path", "title", "referrer_host", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "country", "province", "city", "os", "browser", "device", "lib" ] } }, { "name": "property", "in": "query", "required": false, "schema": { "type": "string" } }, { "description": "time bucket", "name": "grain", "in": "query", "required": false, "schema": { "type": "string", "default": "day", "enum": [ "hour", "day", "week", "month" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_explore" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/funnel": { "get": { "tags": [ "analytics" ], "description": "Ordered funnel: users per step, conversion from previous and first step. Longest range: 90 days.", "operationId": "funnel", "summary": "Funnel · 漏斗", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "comma separated event names, 2 to 8, in order", "name": "steps", "in": "query", "required": true, "schema": { "type": "string" } }, { "description": "max hours between adjacent steps", "name": "window_hours", "in": "query", "required": false, "schema": { "type": "integer", "default": "24", "maximum": 168, "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_funnel" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/heatmap": { "get": { "tags": [ "analytics" ], "description": "Click cells (10px) or stay positions of one page and the most clicked elements. Longest range: 31 days.", "operationId": "heatmap", "summary": "Heatmap · 热力图", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "page path", "name": "url_path", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "default": "click", "enum": [ "click", "stay" ] } }, { "description": "viewport width band", "name": "viewport", "in": "query", "required": false, "schema": { "type": "string", "default": "all", "enum": [ "all", "lg", "md", "sm" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_heatmap" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/overview": { "get": { "tags": [ "analytics" ], "description": "PV, UV, events, sessions, sessions per user, average duration, bounce rate, top pages / referrers / regions. Longest range: 366 days.", "operationId": "overview", "summary": "Overview · 数据概览", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_overview" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/pages": { "get": { "tags": [ "analytics" ], "description": "Pageviews, visitors and share by URL path. Longest range: 366 days.", "operationId": "pages", "summary": "Pages · 受访页面", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_pages" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/pages/entry": { "get": { "tags": [ "analytics" ], "description": "First page of sessions. Longest range: 31 days.", "operationId": "pages_entry", "summary": "Entry pages · 入口页", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_pages_entry" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/pages/exit": { "get": { "tags": [ "analytics" ], "description": "Last page of sessions. Longest range: 31 days.", "operationId": "pages_exit", "summary": "Exit pages · 退出页", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_pages_exit" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/pages/structure": { "get": { "tags": [ "analytics" ], "description": "Pageviews grouped by the first 1-3 path segments. Longest range: 366 days.", "operationId": "pages_structure", "summary": "Page structure · 结构化页面", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "path prefix depth", "name": "depth", "in": "query", "required": false, "schema": { "type": "integer", "default": "2", "maximum": 3, "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_pages_structure" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/path": { "get": { "tags": [ "analytics" ], "description": "Top 10 next events within 30 minutes after an event. Longest range: 31 days.", "operationId": "path", "summary": "Paths · 路径", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "name": "event", "in": "query", "required": false, "schema": { "type": "string", "default": "$pageview" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_path" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/profiles/{distinctId}": { "get": { "tags": [ "analytics" ], "description": "One user's first/last visit, totals, latest region and device, touches and a timeline of up to 200 events", "operationId": "profile", "summary": "User profile · 用户画像", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "distinctId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_profile" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/property-keys": { "get": { "tags": [ "analytics" ], "description": "Filterable columns and property keys. Longest range: 366 days.", "operationId": "property_keys", "summary": "Property keys · 属性键", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "name": "event", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_property_keys" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/replays": { "get": { "tags": [ "analytics" ], "description": ". Longest range: 31 days.", "operationId": "replays", "summary": "Replays · 会话回放列表", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "name": "distinct_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "50", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_replays" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/search/external": { "get": { "tags": [ "analytics" ], "description": "Keywords from search engine referrers; an empty keyword means not provided. Longest range: 31 days.", "operationId": "search_external", "summary": "Search engines · 站外搜索", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_search_external" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/search/internal": { "get": { "tags": [ "analytics" ], "description": "Search terms from the page URL query. Longest range: 31 days.", "operationId": "search_internal", "summary": "Site search · 站内搜索", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_search_internal" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/summary": { "get": { "tags": [ "analytics" ], "description": "PV, UV, events, sessions, average duration and bounce rate per time bucket. Longest range: 366 days.", "operationId": "summary", "summary": "Summary · 数据汇总", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "time bucket", "name": "grain", "in": "query", "required": false, "schema": { "type": "string", "default": "day", "enum": [ "hour", "day", "week", "month" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_summary" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/trend": { "get": { "tags": [ "analytics" ], "description": "One metric over time buckets; UV per bucket is deduplicated inside the bucket. Longest range: 366 days.", "operationId": "trend", "summary": "Trend · 趋势分析", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "time bucket", "name": "grain", "in": "query", "required": false, "schema": { "type": "string", "default": "day", "enum": [ "hour", "day", "week", "month" ] } }, { "description": "metric", "name": "metric", "in": "query", "required": false, "schema": { "type": "string", "default": "pv", "enum": [ "pv", "uv", "event_cnt", "session_cnt" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_trend" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/users/active": { "get": { "tags": [ "analytics" ], "description": "DAU, WAU (Monday to date) and MAU (month to date) per day, plus active-days distribution. Longest range: 366 days.", "operationId": "users_active", "summary": "Active users · 活跃用户", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_users_active" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/users/churn": { "get": { "tags": [ "analytics" ], "description": "Users active in the previous equal-length period but not in this one. Longest range: 90 days.", "operationId": "users_churn", "summary": "Churn · 流失", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_users_churn" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/users/loyalty": { "get": { "tags": [ "analytics" ], "description": "Visitors bucketed by session count, average session duration and average depth. Longest range: 90 days.", "operationId": "users_loyalty", "summary": "Loyalty · 忠诚度", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_users_loyalty" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/users/retention": { "get": { "tags": [ "analytics" ], "description": "Cohorts by first start event date and the share returning N days/weeks later. Longest range: 90 days.", "operationId": "retention", "summary": "Retention · 留存", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "cohort event", "name": "start_event", "in": "query", "required": false, "schema": { "type": "string", "default": "$pageview" } }, { "description": "return event", "name": "return_event", "in": "query", "required": false, "schema": { "type": "string", "default": "$pageview" } }, { "name": "unit", "in": "query", "required": false, "schema": { "type": "string", "default": "day", "enum": [ "day", "week" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_retention" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/users/silent-return": { "get": { "tags": [ "analytics" ], "description": "Dormant users (no pageview for N days) and returning users. Longest range: 90 days.", "operationId": "silent_return", "summary": "Returning & dormant · 回流与沉默", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "name": "silent_days", "in": "query", "required": false, "schema": { "type": "string", "default": "7", "enum": [ "7", "14", "30" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_silent_return" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/visitors/channels": { "get": { "tags": [ "analytics" ], "description": "Pageviews by UTM value; an empty name means not set. Longest range: 366 days.", "operationId": "channels", "summary": "Channels · 渠道", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "UTM column", "name": "dim", "in": "query", "required": false, "schema": { "type": "string", "default": "utm_source", "enum": [ "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_channels" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/visitors/devices": { "get": { "tags": [ "analytics" ], "description": "Pageviews by device type, operating system or browser. Longest range: 366 days.", "operationId": "devices", "summary": "Devices · 设备", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "device dimension", "name": "dim", "in": "query", "required": false, "schema": { "type": "string", "default": "device", "enum": [ "device", "os", "browser" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_devices" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/visitors/geo": { "get": { "tags": [ "analytics" ], "description": "Pageviews and visitors by country, province or city. Longest range: 366 days.", "operationId": "geo", "summary": "Regions · 地域", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" }, { "description": "region level", "name": "level", "in": "query", "required": false, "schema": { "type": "string", "default": "country", "enum": [ "country", "province", "city" ] } }, { "description": "parent region name for drill down", "name": "parent", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_geo" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/visitors/new-returning": { "get": { "tags": [ "analytics" ], "description": "New visitors (first seen in the range) and returning visitors per day. Longest range: 90 days.", "operationId": "new_returning", "summary": "New vs returning · 新老访客", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_new_returning" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/projects/{projectId}/visitors/referrers": { "get": { "tags": [ "analytics" ], "description": "Pageviews by referrer host; an empty name means direct traffic. Longest range: 366 days.", "operationId": "referrers", "summary": "Referrers · 来源网站", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "description": "Start date (project time zone), inclusive", "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "End date (project time zone), inclusive", "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-09-18" } }, { "description": "prev = also return the previous period of equal length", "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "prev" ] } }, { "description": "Filter key,op,value (op: eq, neq, contains, exists). Repeat for AND.", "name": "pf", "in": "query", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Data_referrers" } } } ] } } } }, "400": { "description": "Invalid parameter or range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "No permission for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited (60 per minute per key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "The project's shard is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "components": { "schemas": { "Data_attribution": { "type": "object", "properties": { "event": { "type": "string" }, "lookback_days": { "type": "integer", "format": "int64" }, "model": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "channel_type": { "type": "string" }, "conversions": { "type": "number" }, "ratio": { "type": "number" }, "source": { "type": "string" }, "users": { "type": "integer", "format": "int64" } } } } } }, "Data_channels": { "type": "object", "properties": { "dim": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "description": "empty string = direct / not set / unknown", "type": "string" }, "prev_pv": { "type": "integer", "format": "int64" }, "prev_uv": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "ratio": { "type": "number" }, "uv": { "type": "integer", "format": "int64" } } } }, "total_pv": { "type": "integer", "format": "int64" } } }, "Data_devices": { "type": "object", "properties": { "dim": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "description": "empty string = direct / not set / unknown", "type": "string" }, "prev_pv": { "type": "integer", "format": "int64" }, "prev_uv": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "ratio": { "type": "number" }, "uv": { "type": "integer", "format": "int64" } } } }, "total_pv": { "type": "integer", "format": "int64" } } }, "Data_event_logs": { "type": "object", "properties": { "next_before": { "description": "cursor for the next page (pass as before)", "type": "string", "nullable": true }, "rows": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "properties": { "type": "object" }, "anonymous_id": { "type": "string" }, "browser": { "type": "string" }, "browser_version": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "device": { "type": "string" }, "distinct_id": { "type": "string" }, "event": { "type": "string" }, "event_id": { "type": "string" }, "event_time": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string" }, "event_type": { "type": "string" }, "ip": { "type": "string" }, "is_login": { "type": "boolean" }, "lib": { "type": "string" }, "lib_version": { "type": "string" }, "login_id": { "type": "string" }, "os": { "type": "string" }, "os_version": { "type": "string" }, "province": { "type": "string" }, "received_at": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string" }, "referrer": { "type": "string" }, "referrer_host": { "type": "string" }, "url": { "type": "string" }, "url_path": { "type": "string" }, "utm_campaign": { "type": "string" }, "utm_content": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_source": { "type": "string" }, "utm_term": { "type": "string" } } } } } }, "Data_event_names": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "cnt": { "type": "integer", "format": "int64" }, "display_name": { "type": "string" }, "event": { "type": "string" }, "visible": { "type": "boolean" } } } } } }, "Data_events": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "cnt": { "type": "integer", "format": "int64" }, "display_name": { "type": "string" }, "event": { "type": "string" }, "per_user": { "type": "number" }, "prev_cnt": { "type": "integer", "format": "int64" }, "prev_users": { "type": "integer", "format": "int64" }, "users": { "type": "integer", "format": "int64" } } } }, "trend": { "type": "array", "items": { "type": "object", "properties": { "cnt": { "type": "integer", "format": "int64" }, "date": { "type": "string", "format": "date", "example": "2026-09-18" }, "users": { "type": "integer", "format": "int64" } } }, "nullable": true } } }, "Data_experiment": { "type": "object", "properties": { "name": { "type": "string" }, "conclusion": { "type": "string", "enum": [ "significant", "not_significant", "insufficient" ] }, "experiment_id": { "type": "string" }, "goal_event": { "type": "string" }, "key": { "type": "string" }, "started_at": { "type": "string", "nullable": true }, "status": { "type": "string" }, "stopped_at": { "type": "string", "nullable": true }, "traffic": { "type": "integer", "format": "int64" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "converted": { "type": "integer", "format": "int64" }, "key": { "type": "string" }, "lift": { "type": "number", "nullable": true }, "rate": { "type": "number" }, "significant": { "type": "boolean" }, "users": { "type": "integer", "format": "int64" }, "variant_id": { "type": "string" }, "weight": { "type": "integer", "format": "int64" }, "z": { "type": "number", "nullable": true } } } }, "winner": { "type": "string", "nullable": true } } }, "Data_experiments": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "entered_users": { "type": "integer", "format": "int64" }, "experiment_id": { "type": "string" }, "goal_event": { "type": "string" }, "key": { "type": "string" }, "started_at": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "draft", "running", "stopped" ] }, "traffic": { "type": "integer", "format": "int64" } } } } } }, "Data_explore": { "type": "object", "properties": { "dim": { "type": "string" }, "event": { "type": "string" }, "grain": { "type": "string" }, "groups": { "type": "array", "items": { "type": "string" } }, "measure": { "type": "string" }, "property": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "group": { "type": "string" }, "value": { "type": "number" } } } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string" }, "value": { "type": "number" } } } } } }, "Data_funnel": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "conv_from_first": { "type": "number" }, "conv_from_prev": { "type": "number" }, "event": { "type": "string" }, "users": { "type": "integer", "format": "int64" } } } }, "window_hours": { "type": "integer", "format": "int64" } } }, "Data_geo": { "type": "object", "properties": { "level": { "type": "string" }, "parent": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "description": "empty string = direct / not set / unknown", "type": "string" }, "prev_pv": { "type": "integer", "format": "int64" }, "prev_uv": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "ratio": { "type": "number" }, "uv": { "type": "integer", "format": "int64" } } } }, "total_pv": { "type": "integer", "format": "int64" } } }, "Data_heatmap": { "type": "object", "properties": { "title": { "type": "string" }, "cells": { "type": "array", "items": { "type": "object", "properties": { "cnt": { "type": "integer", "format": "int64" }, "dur": { "type": "number" }, "x": { "type": "integer", "format": "int64" }, "y": { "type": "integer", "format": "int64" } } } }, "elements": { "type": "array", "items": { "type": "object", "properties": { "cnt": { "type": "integer", "format": "int64" }, "selector": { "type": "string" }, "text": { "type": "string" } } } }, "kind": { "type": "string" }, "page_url": { "type": "string" }, "total": { "type": "integer", "format": "int64" }, "url_path": { "type": "string" }, "viewport": { "type": "string" }, "viewport_w": { "type": "integer", "format": "int64" } } }, "Data_new_returning": { "type": "object", "properties": { "new": { "type": "object", "properties": { "avg_duration_sec": { "type": "number" }, "bounce_rate": { "type": "number" }, "pv": { "type": "integer", "format": "int64" }, "users": { "type": "integer", "format": "int64" } } }, "returning": { "type": "object", "properties": { "avg_duration_sec": { "type": "number" }, "bounce_rate": { "type": "number" }, "pv": { "type": "integer", "format": "int64" }, "users": { "type": "integer", "format": "int64" } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-18" }, "new_users": { "type": "integer", "format": "int64" }, "returning_users": { "type": "integer", "format": "int64" } } } } } }, "Data_overview": { "type": "object", "properties": { "avg_duration_sec": { "type": "number", "nullable": true }, "bounce_rate": { "type": "number", "nullable": true }, "compare": { "type": "object", "properties": { "avg_duration_sec": { "type": "number", "nullable": true }, "bounce_rate": { "type": "number", "nullable": true }, "event_cnt": { "type": "integer", "format": "int64" }, "from": { "type": "string", "format": "date", "example": "2026-09-18" }, "pv": { "type": "integer", "format": "int64" }, "session_cnt": { "type": "integer", "format": "int64", "nullable": true }, "session_per_user": { "type": "number", "nullable": true }, "to": { "type": "string", "format": "date", "example": "2026-09-18" }, "uv": { "type": "integer", "format": "int64" } }, "nullable": true }, "event_cnt": { "type": "integer", "format": "int64" }, "ingest": { "type": "object", "properties": { "shard_up": { "type": "boolean" }, "stream_pending": { "type": "integer", "format": "int64" } } }, "partial": { "type": "array", "items": { "type": "string", "enum": [ "session" ] } }, "pv": { "type": "integer", "format": "int64" }, "session_cnt": { "type": "integer", "format": "int64", "nullable": true }, "session_per_user": { "type": "number", "nullable": true }, "top_pages": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "pv": { "type": "integer", "format": "int64" }, "uv": { "type": "integer", "format": "int64" } } } }, "top_referrers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "pv": { "type": "integer", "format": "int64" }, "uv": { "type": "integer", "format": "int64" } } } }, "top_regions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "pv": { "type": "integer", "format": "int64" }, "uv": { "type": "integer", "format": "int64" } } } }, "uv": { "type": "integer", "format": "int64" } } }, "Data_pages": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "avg_stay_sec": { "type": "number", "nullable": true }, "pv": { "type": "integer", "format": "int64" }, "ratio": { "type": "number" }, "uv": { "type": "integer", "format": "int64" } } } }, "total_pv": { "type": "integer", "format": "int64" } } }, "Data_pages_entry": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "bounce_rate": { "type": "number" }, "sessions": { "type": "integer", "format": "int64" }, "users": { "type": "integer", "format": "int64" } } } } } }, "Data_pages_exit": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "exit_rate": { "type": "number" }, "exits": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "users": { "type": "integer", "format": "int64" } } } } } }, "Data_pages_structure": { "type": "object", "properties": { "depth": { "type": "integer", "format": "int64" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "integer", "format": "int64" }, "prefix": { "type": "string" }, "pv": { "type": "integer", "format": "int64" }, "uv": { "type": "integer", "format": "int64" } } } } } }, "Data_path": { "type": "object", "properties": { "event": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "cnt": { "type": "integer", "format": "int64" }, "next_event": { "type": "string" }, "users": { "type": "integer", "format": "int64" } } } } } }, "Data_profile": { "type": "object", "properties": { "distinct_id": { "type": "string" }, "event_total": { "type": "integer", "format": "int64" }, "first_time": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string", "nullable": true }, "first_touch": { "type": "object", "properties": { "click_id_type": { "type": "string" }, "referrer_host": { "type": "string" }, "time": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string" }, "traffic_source_type": { "type": "string", "enum": [ "paid", "organic_search", "social", "referral", "direct" ] }, "utm_campaign": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_source": { "type": "string" } }, "nullable": true }, "has_replay": { "type": "boolean" }, "is_login": { "type": "boolean" }, "last_browser": { "type": "string" }, "last_city": { "type": "string" }, "last_country": { "type": "string" }, "last_device": { "type": "string" }, "last_os": { "type": "string" }, "last_province": { "type": "string" }, "last_time": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string", "nullable": true }, "latest_profile": { "type": "object", "properties": { "properties": { "type": "object" }, "time": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string" } }, "nullable": true }, "latest_touch": { "type": "object", "properties": { "click_id_type": { "type": "string" }, "referrer_host": { "type": "string" }, "time": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string" }, "traffic_source_type": { "type": "string", "enum": [ "paid", "organic_search", "social", "referral", "direct" ] }, "utm_campaign": { "type": "string" }, "utm_medium": { "type": "string" }, "utm_source": { "type": "string" } }, "nullable": true }, "login_id": { "type": "string" }, "pv_total": { "type": "integer", "format": "int64" }, "session_total": { "type": "integer", "format": "int64" }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "duration_sec": { "type": "integer", "format": "int64" }, "events": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "properties": { "type": "object" }, "event": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "referrer_host": { "type": "string" }, "time": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string" }, "url_path": { "type": "string" } } } }, "pages": { "type": "integer", "format": "int64" }, "start": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string" } } } } } }, "Data_property_keys": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "boolean" }, "display_name": { "type": "string" }, "key": { "type": "string" }, "value_type": { "type": "string" } } } } } }, "Data_referrers": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "description": "empty string = direct / not set / unknown", "type": "string" }, "prev_pv": { "type": "integer", "format": "int64" }, "prev_uv": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "ratio": { "type": "number" }, "uv": { "type": "integer", "format": "int64" } } } }, "total_pv": { "type": "integer", "format": "int64" } } }, "Data_replays": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "bytes": { "type": "integer", "format": "int64" }, "chunks": { "type": "integer", "format": "int64" }, "device": { "type": "string" }, "distinct_id": { "type": "string" }, "duration_sec": { "type": "integer", "format": "int64" }, "entry_path": { "type": "string" }, "pages": { "type": "integer", "format": "int64" }, "replay_id": { "type": "string" }, "started_at": { "description": "project time zone, YYYY-MM-DD HH:MM:SS(.mmm)", "type": "string" } } } } } }, "Data_retention": { "type": "object", "properties": { "average": { "type": "array", "items": { "type": "number" } }, "cohorts": { "type": "array", "items": { "type": "object", "properties": { "rates": { "type": "array", "items": { "type": "number" } }, "size": { "type": "integer", "format": "int64" }, "start_date": { "type": "string", "format": "date", "example": "2026-09-18" } } } }, "return_event": { "type": "string" }, "start_event": { "type": "string" }, "unit": { "type": "string" } } }, "Data_search_external": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "cnt": { "type": "integer", "format": "int64" }, "engine": { "type": "string" }, "ratio": { "type": "number" }, "users": { "type": "integer", "format": "int64" } } } }, "total": { "type": "integer", "format": "int64" } } }, "Data_search_internal": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "cnt": { "type": "integer", "format": "int64" }, "engine": { "type": "string" }, "ratio": { "type": "number" }, "users": { "type": "integer", "format": "int64" } } } }, "total": { "type": "integer", "format": "int64" } } }, "Data_silent_return": { "type": "object", "properties": { "returned": { "type": "integer", "format": "int64" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-18" }, "returned": { "type": "integer", "format": "int64" }, "silent": { "type": "integer", "format": "int64" } } } }, "silent": { "type": "integer", "format": "int64" }, "silent_days": { "type": "integer", "format": "int64" } } }, "Data_summary": { "type": "object", "properties": { "compare_rows": { "type": "array", "items": { "type": "object", "properties": { "avg_duration_sec": { "type": "number", "nullable": true }, "bounce_rate": { "type": "number", "nullable": true }, "bucket": { "description": "YYYY-MM-DD (week = Monday, month = 1st) or YYYY-MM-DD HH:00", "type": "string" }, "event_cnt": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "session_cnt": { "type": "integer", "format": "int64", "nullable": true }, "uv": { "type": "integer", "format": "int64" } } }, "nullable": true }, "grain": { "type": "string" }, "partial": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "avg_duration_sec": { "type": "number", "nullable": true }, "bounce_rate": { "type": "number", "nullable": true }, "bucket": { "description": "YYYY-MM-DD (week = Monday, month = 1st) or YYYY-MM-DD HH:00", "type": "string" }, "event_cnt": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "session_cnt": { "type": "integer", "format": "int64", "nullable": true }, "uv": { "type": "integer", "format": "int64" } } } } } }, "Data_trend": { "type": "object", "properties": { "compare_rows": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "event_cnt": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "session_cnt": { "type": "integer", "format": "int64" }, "uv": { "type": "integer", "format": "int64" }, "value": { "type": "number" } } }, "nullable": true }, "grain": { "type": "string" }, "metric": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "event_cnt": { "type": "integer", "format": "int64" }, "pv": { "type": "integer", "format": "int64" }, "session_cnt": { "type": "integer", "format": "int64" }, "uv": { "type": "integer", "format": "int64" }, "value": { "type": "number" } } } } } }, "Data_users_active": { "type": "object", "properties": { "distribution": { "type": "array", "items": { "type": "object", "properties": { "days": { "type": "integer", "format": "int64" }, "users": { "type": "integer", "format": "int64" } } }, "nullable": true }, "rows": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "example": "2026-09-18" }, "dau": { "type": "integer", "format": "int64" }, "mau": { "type": "integer", "format": "int64" }, "wau": { "type": "integer", "format": "int64" } } } } } }, "Data_users_churn": { "type": "object", "properties": { "churn_rate": { "type": "number" }, "churned": { "type": "integer", "format": "int64" }, "prev_from": { "type": "string", "format": "date", "example": "2026-09-18" }, "prev_to": { "type": "string", "format": "date", "example": "2026-09-18" }, "prev_users": { "type": "integer", "format": "int64" }, "sample": { "type": "array", "items": { "type": "string" } } } }, "Data_users_loyalty": { "type": "object", "properties": { "depth": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "ratio": { "type": "number" }, "users": { "type": "integer", "format": "int64" } } } }, "duration": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "ratio": { "type": "number" }, "users": { "type": "integer", "format": "int64" } } } }, "total_users": { "type": "integer", "format": "int64" }, "visits": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "ratio": { "type": "number" }, "users": { "type": "integer", "format": "int64" } } } } } }, "Envelope": { "required": [ "code", "message", "data" ], "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "data": {}, "message": { "type": "string" } } }, "ErrorCode": { "description": "0 ok; 40001 bad parameter; 40002 not configured; 40003 setup incomplete; 40101 unauthenticated; 40301 forbidden; 40401 not found; 40901 conflict; 41301 too large; 42901 too many requests; 50001 internal; 50002 query timeout; 50301 dependency unavailable", "type": "integer", "enum": [ 0, 40001, 40002, 40003, 40101, 40301, 40401, 40901, 41301, 42901, 50001, 50002, 50301 ] }, "ErrorEnvelope": { "required": [ "code", "message" ], "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "data": { "type": "object", "nullable": true }, "message": { "description": "Localized by Accept-Language (zh-CN or en)", "type": "string" } } }, "Project": { "type": "object", "properties": { "name": { "type": "string" }, "project_code": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" }, "timezone": { "type": "string" } } }, "ProjectList": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } }, "securitySchemes": { "bearerAuth": { "description": "User API key, prefix evs_", "type": "http", "scheme": "bearer" } } } }