文档指南API 参考Cloudv2

报告

通过 API 使用报告。

端点

GET /api/reports
POST /api/reports
GET /api/reports/:reportId
POST /api/reports/:reportId
DELETE /api/reports/:reportId
POST /api/reports/attribution
POST /api/reports/breakdown
POST /api/reports/funnel
POST /api/reports/goal
POST /api/reports/journey
POST /api/reports/performance
POST /api/reports/retention
POST /api/reports/revenue
POST /api/reports/utm

过滤器

现在所有报告都可以通过请求体中的 filters 属性进行过滤。

ParameterTypeDescription
pathstringURL 的名称。
referrerstring引荐来源名称。
titlestring页面标题名称。
querystring查询参数名称。
browserstring浏览器名称。
osstring操作系统名称。
devicestring设备名称（例如：Mobile）。
countrystring国家/地区名称。
regionstring地区/州/省名称。
citystring城市名称。
languagestring浏览器语言名称。
hostnamestring主机名名称。
tagstring标签名称。
eventstring事件名称。
distinctIdstringdistinct ID 的名称。
utmSourcestringUTM 来源。
utmMediumstringUTM 媒介。
utmCampaignstringUTM 活动名称。
utmContentstringUTM 内容。
utmTermstringUTM 术语。
segmentuuid分段的 UUID。
cohortuuid同组群的 UUID。

请求体

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "attribution",
  "filters": { "os": "Mac OS", "device": "desktop" },
  "parameters": {
    "startDate": "2025-10-19T07:00:00.000Z",
    "endDate": "2025-10-26T06:59:59.999Z",
    "timezone": "America/Los_Angeles",
    "model": "first-click",
    "type": "path",
    "step": "/"
  }
}

GET /api/reports

根据网站 ID 获取所有报告。

参数

ParameterTypeDescription
websiteIdstring你的网站 ID。
typestring报告类型（attribution | breakdown | funnel | goal | journey | retention | revenue | utm）。
pagenumber（可选，默认 1）确定页码。
pageSizenumber（可选）确定返回多少条结果。

示例响应

{
  "data": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "goal",
      "name": "访问 /pricing",
      "description": "测试",
      "parameters": {
        "type": "path",
        "value": "/pricing"
      },
      "createdAt": "2025-07-23T17:28:55.192Z",
      "updatedAt": "2025-10-07T07:46:57.918Z"
    },
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "goal",
      "name": "触发 live-demo-button",
      "description": "",
      "parameters": {
        "type": "event",
        "value": "live-demo-button"
      },
      "createdAt": "2025-10-07T07:46:24.120Z",
      "updatedAt": "2025-10-07T07:46:24.120Z"
    }
  ],
  "count": 2,
  "page": 1,
  "pageSize": 20
}

POST /api/reports

创建报告。

参数

ParameterTypeDescription
websiteIdstring你的网站 ID。
typestring报告类型（attribution | breakdown | funnel | goal | journey | retention | revenue | utm）。
namestring报告名称。
descriptionstring（可选）报告描述。
parametersobject报告参数。

请求体

{
  "name": "触发登录按钮 ",
  "parameters": { "type": "event", "value": "login-button-header" },
  "type": "goal",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

示例响应

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "goal",
  "name": "触发登录按钮 ",
  "description": "",
  "parameters": {
    "type": "event",
    "value": "login-button-header"
  },
  "createdAt": "2025-10-14T00:12:33.203Z",
  "updatedAt": "2025-10-14T00:12:33.203Z"
}

GET /api/reports/:reportId

根据 ID 获取报告。

示例响应

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "goal",
  "name": "触发登录按钮 ",
  "description": "",
  "parameters": {
    "type": "event",
    "value": "login-button-header"
  },
  "createdAt": "2025-10-14T00:12:33.203Z",
  "updatedAt": "2025-10-14T00:12:33.203Z"
}

POST /api/reports/:reportId

更新报告。

参数

ParameterTypeDescription
websiteIdstring你的网站 ID。
typestring报告类型（attribution | breakdown | funnel | goal | journey | retention | revenue | utm）。
namestring报告名称。
descriptionstring（可选）报告描述。
parametersobject报告参数。

请求体

{
  "name": "触发登录按钮 ",
  "parameters": { "type": "event", "value": "login-button-header" },
  "type": "goal",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

示例响应

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "goal",
  "name": "触发登录按钮 ",
  "description": "",
  "parameters": {
    "type": "event",
    "value": "login-button-header"
  },
  "createdAt": "2025-10-14T00:12:33.203Z",
  "updatedAt": "2025-10-14T00:12:33.203Z"
}

DELETE /api/reports/:reportId

删除报告。

示例响应

{
  "ok": true
}

POST /api/reports/attribution

查看用户如何与您的营销活动互动以及哪些因素驱动转化。

参数

ParameterTypeDescription
websiteIdstring你的网站 ID。
typestring报告类型（attribution）。
filtersobject可接受过滤参数。
startDatestring开始日期。
endDatestring结束日期。
modelstring归因模型（firstClick | lastClick）。
typestring转化类型（path | event）。
stepstring转化步骤。

请求体

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "attribution",
  "filters": { "os": "Mac OS" },
  "parameters": {
    "startDate": "2025-10-19T07:00:00.000Z",
    "endDate": "2025-10-26T06:59:59.999Z",
    "model": "first-click",
    "type": "path",
    "step": "/"
  }
}

示例响应

{
  "referrer": [
    {
      "name": "google.com",
      "value": 30082
    },
    {
      "name": "chatgpt.com",
      "value": 1672
    }
  ],
  "paidAds": [
    {
      "name": "Facebook / Meta",
      "value": 106
    },
    {
      "name": "Google Ads",
      "value": 6
    }
  ],
  "utm_source": [
    {
      "name": "coolify.io",
      "value": 465
    },
    {
      "name": "chatgpt.com",
      "value": 338
    }
  ],
  "utm_medium": [
    {
      "name": "referral",
      "value": 75
    },
    {
      "name": "email",
      "value": 16
    }
  ],
  "utm_campaign": [
    {
      "name": "navigation",
      "value": 60
    },
    {
      "name": "website_analytics",
      "value": 8
    }
  ],
  "utm_content": [
    {
      "name": "comparison-page",
      "value": 1
    },
    {
      "name": "sidebar-cta",
      "value": 1
    }
  ],
  "utm_term": [
    {
      "name": "data analysis",
      "value": 1
    },
    {
      "name": "0_df65b6d7c8-e2c14ebdc7-59136105",
      "value": 1
    }
  ],
  "total": {
    "pageviews": 171481,
    "visitors": 104727,
    "visits": 138391
  }
}

POST /api/reports/breakdown

通过使用分段和过滤器更深入地了解您的数据。

参数

ParameterTypeDescription
websiteIdstring你的网站 ID。
typestring报告类型（breakdown）。
filtersobject可接受过滤参数。
startDatestring开始日期。
endDatestring结束日期。
fieldsarray列字段列表。

可用字段

path | title | query | referrer | browser | os | device | country | region | city | hostname | tag | event | distinctId | utmSource | utmMedium | utmCampaign | utmContent | utmTerm |

请求体

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "breakdown",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "fields": ["os", "country"]
  }
}

示例响应

[
  {
    "views": 37856,
    "visitors": 9229,
    "visits": 13145,
    "bounces": 8105,
    "totaltime": 12985151,
    "os": "Mac OS",
    "country": "US"
  },
  {
    "views": 24399,
    "visitors": 6628,
    "visits": 10673,
    "bounces": 7119,
    "totaltime": 21398417,
    "os": "Windows 10",
    "country": "US"
  },
  {
    "views": 21561,
    "visitors": 4916,
    "visits": 6532,
    "bounces": 3452,
    "totaltime": 22984512,
    "os": "Mac OS",
    "country": "DE"
  },
  {
    "views": 12977,
    "visitors": 2976,
    "visits": 4180,
    "bounces": 2440,
    "totaltime": 9962317,
    "os": "Windows 10",
    "country": "DE"
  }
]

POST /api/reports/funnel

了解用户的转化和流失率。

参数

ParameterTypeDescription
websiteIdstring你的网站 ID。
typestring报告类型（funnel）。
filtersobject可接受过滤参数。
startDatestring开始日期。
endDatestring结束日期。
stepsarray至少需要两个。每个步骤都有一个 type（path | event）和一个 value。
windownumber漏斗步骤之间被视为一次转化的天数窗口。

请求体

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "funnel",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "steps": [
      { "type": "path", "value": "/" },
      { "type": "event", "value": "live-demo-button" }
    ],
    "window": 60
  }
}

示例响应

[
  {
    "type": "path",
    "value": "/",
    "visitors": 106594,
    "previous": 0,
    "dropped": 0,
    "dropoff": null,
    "remaining": 1
  },
  {
    "type": "event",
    "value": "live-demo-button",
    "visitors": 10269,
    "previous": 106594,
    "dropped": 96325,
    "dropoff": 0.9036624950747697,
    "remaining": 0.09633750492523031
  }
]

POST /api/reports/goal

跟踪您的页面浏览量和事件目标。

参数

ParameterTypeDescription
websiteIdstring您的网站 ID。
typestring报告类型（goal）。
filtersobject可接受筛选参数。
startDatestring开始日期。
endDatestring结束日期。
typestring转化类型（path | event）。
valuestring转化步骤值。

请求体

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "goal",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "type": "event",
    "value": "live-demo-button"
  }
}

示例响应

{
  "num": 11935,
  "total": 50602
}

POST /api/reports/journey

了解用户如何在您的网站中导航。

参数

ParameterTypeDescription
websiteIdstring您的网站 ID。
typestring报告类型（journey）。
filtersobject可接受筛选参数。
startDatestring开始日期。
endDatestring结束日期。
stepsnumber步骤数，从 3 到 7。
startStepstring起始步骤 URL 或事件名称。
endStepstring（可选）结束步骤 URL 或事件名称。

请求体

{
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "type": "journey",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "steps": 3,
    "startStep": "/",
    "endStep": "/pricing"
  }
}

示例响应

[
  {
    "items": ["/", "/pricing", null, null],
    "count": 6433
  },
  {
    "items": ["/", "live-demo-button", "/pricing", null],
    "count": 918
  },
  {
    "items": ["/", "/features", "/pricing", null],
    "count": 857
  },
  {
    "items": ["/", "/pricing", null],
    "count": 434
  },
  {
    "items": ["/", "/pricing", null],
    "count": 306
  },
  {
    "items": ["/", "/docs", "/pricing", null],
    "count": 257
  },
  {
    "items": ["/", "get-started-button", "/pricing", null],
    "count": 237
  },
  {
    "items": ["/", "login-button-header", "/pricing", null],
    "count": 102
  }
]

POST /api/reports/performance

获取给定日期范围的 Core Web Vitals 性能指标。

参数

ParameterTypeDescription
websiteIdstring您的网站 ID。
typestring报告类型（performance）。
filtersobject可接受筛选参数。
startDatestring开始日期。
endDatestring结束日期。
unitstring（可选）时间单位（year | month | hour | day）。
timezonestring（可选）时区（例如 America/Los_Angeles）。
metricstring（可选）要关注的指标（lcp | inp | cls | fcp | ttfb）。

请求体

{
  "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "performance",
  "filters": {},
  "parameters": {
    "startDate": "2025-10-01T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "timezone": "America/Los_Angeles",
    "metric": "lcp"
  }
}

示例响应

{
    "chart": [
        {
            "t": "2026-03-11T16:00:00Z",
            "p50": 24748,
            "p75": 24748,
            "p95": 24748
        },
        {
            "t": "2026-03-11T17:00:00Z",
            "p50": 920,
            "p75": 920,
            "p95": 920
        },
        {
            "t": "2026-03-11T21:00:00Z",
            "p50": 1408,
            "p75": 1408,
            "p95": 1408
        }
    ],
    "summary": {
        "lcp": {
            "p50": 1408,
            "p75": 13078,
            "p95": 22413.9
        },
        "inp": {
            "p50": 48,
            "p75": 56,
            "p95": 86.3
        },
        "cls": {
            "p50": 0.0015,
            "p75": 0.0067,
            "p95": 0.0231
        },
        "fcp": {
            "p50": 720,
            "p75": 10264,
            "p95": 17899.1
        },
        "ttfb": {
            "p50": 274.7,
            "p75": 9062.2,
            "p95": 16092.2
        },
        "count": 28
    },
    "pages": [
        {
            "name": "/analytics/websites",
            "p50": 1408,
            "p75": 1408,
            "p95": 1408,
            "count": 1
        }
    ],
    "pageTitles": [
        {
            "name": "Websites | Umami",
            "p50": 1408,
            "p75": 13078,
            "p95": 22413.9,
            "count": 8
        },
        {
            "name": "Pixels | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 2
        },
        {
            "name": "Settings | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 1
        },
        {
            "name": "Board | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 6
        },
        {
            "name": "Links | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 2
        },
        {
            "name": "Boards | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 2
        },
        {
            "name": "Design Board | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 3
        },
        {
            "name": "Edit Link | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 1
        },
        {
            "name": "Edit Pixel | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 1
        },
        {
            "name": "Edit Board | Umami",
            "p50": null,
            "p75": null,
            "p95": null,
            "count": 2
        }
    ],
    "devices": [
        {
            "name": "laptop",
            "p50": 12834,
            "p75": 18791,
            "p95": 23556.6,
            "count": 27
        },
        {
            "name": "desktop",
            "p50": 1408,
            "p75": 1408,
            "p95": 1408,
            "count": 1
        }
    ],
    "browsers": [
        {
            "name": "chrome",
            "p50": 1408,
            "p75": 13078,
            "p95": 22413.9,
            "count": 28
        }
    ]
}

POST /api/reports/retention

通过跟踪用户回访频率来衡量网站粘性。

参数

ParameterTypeDescription
websiteIdstring您的网站 ID。
typestring报告类型（retention）。
filtersobject可接受筛选参数。
startDatestring开始日期。
endDatestring结束日期。
timezonestring时区（例如 America/Los_Angeles）。

请求体

{
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "type": "retention",
  "filters": {},
  "parameters": {
    "startDate": "2025-10-01T07:00:00.000Z",
    "endDate": "2025-11-01T06:59:59.999Z",
    "timezone": "America/Los_Angeles"
  }
}

示例响应

[
  {
    "date": "2025-10-01T07:00:00Z",
    "day": 0,
    "visitors": 1499,
    "returnVisitors": 1499,
    "percentage": 100
  },
  {
    "date": "2025-10-01T07:00:00Z",
    "day": 1,
    "visitors": 1499,
    "returnVisitors": 151,
    "percentage": 10.073382254836558
  },
  {
    "date": "2025-10-01T07:00:00Z",
    "day": 2,
    "visitors": 1499,
    "returnVisitors": 83,
    "percentage": 5.537024683122081
  },
  {
    "date": "2025-10-01T07:00:00Z",
    "day": 3,
    "visitors": 1499,
    "returnVisitors": 45,
    "percentage": 3.002001334222815
  }
]

POST /api/reports/revenue

获取指定区间的货币信息。用于 Revenue 报告必需，Attribution 报告可选。

参数

ParameterTypeDescription
websiteIdstring您的网站 ID。
typestring报告类型（revenue）。
filtersobject可接受筛选参数。
startDatestring开始日期。
endDatestring结束日期。
timezonestring时区（例如 America/Los_Angeles）。
currencystring货币代码（ISO 4217）。
comparestring（可选）比较周期（prev | yoy）。

请求体

{
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "type": "revenue",
  "filters": {},
  "parameters": {
    "startDate": "2025-07-23T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z",
    "timezone": "America/Los_Angeles",
    "currency": "USD"
  }
}

示例响应

{
    "chart": [
        {
            "x": "revenue-demo",
            "t": "2026-03-11T08:00:00Z",
            "y": 70,
            "count": 2
        },
        {
            "x": "revenue-demo",
            "t": "2026-03-11T09:00:00Z",
            "y": 40,
            "count": 2
        },
        {
            "x": "revenue-demo",
            "t": "2026-03-11T10:00:00Z",
            "y": 80,
            "count": 2
        },
        {
            "x": "revenue-demo",
            "t": "2026-03-11T11:00:00Z",
            "y": 70,
            "count": 2
        },
        {
            "x": "revenue-demo",
            "t": "2026-03-11T12:00:00Z",
            "y": 50,
            "count": 3
        },
        {
            "x": "revenue-demo",
            "t": "2026-03-11T13:00:00Z",
            "y": 10,
            "count": 1
        }
    ],
    "total": {
        "sum": 320,
        "count": 12,
        "unique_count": 12,
        "total_sessions": 1300,
        "average": 26.666666666666668,
        "arpu": 0.24615384615384617,
        "comparison": {
            "sum": 2470,
            "count": 66,
            "unique_count": 66,
            "total_sessions": 2994,
            "average": 37.42424242424242,
            "arpu": 0.8249832999331997
        }
    },
    "country": [
        {
            "name": "GB",
            "value": 100
        },
        {
            "name": "FR",
            "value": 100
        },
        {
            "name": "DE",
            "value": 60
        },
        {
            "name": "US",
            "value": 40
        },
        {
            "name": "CN",
            "value": 20
        }
    ],
    "region": [
        {
            "country": "FR",
            "name": "FR-IDF",
            "value": 100
        },
        {
            "country": "GB",
            "name": "GB-ENG",
            "value": 100
        },
        {
            "country": "DE",
            "name": "DE-HE",
            "value": 60
        },
        {
            "country": "US",
            "name": "US-CA",
            "value": 40
        },
        {
            "country": "CN",
            "name": "CN-GD",
            "value": 20
        }
    ],
    "referrer": [
        {
            "name": "chatgpt.com",
            "value": 100
        },
        {
            "name": "github.com",
            "value": 100
        },
        {
            "name": "google.com",
            "value": 60
        },
        {
            "name": "reddit.com",
            "value": 60
        }
    ],
    "channel": [
        {
            "name": "referral",
            "value": 100
        },
        {
            "name": "organicSearch",
            "value": 100
        },
        {
            "name": "paidSearch",
            "value": 60
        },
        {
            "name": "organicSocial",
            "value": 60
        }
    ]
}

POST /api/reports/utm

通过 UTM 参数跟踪您的营销活动。

参数

ParameterTypeDescription
websiteIdstring您的网站 ID。
typestring报告类型（utm）。
filtersobject可接受筛选参数。
startDatestring开始日期。
endDatestring结束日期。

请求体

{
  "websiteId": "86d4095c-a2a8-4fc8-9521-103e858e2b41",
  "type": "utm",
  "filters": {},
  "parameters": {
    "startDate": "2025-10-14T07:00:00.000Z",
    "endDate": "2025-10-22T06:59:59.999Z"
  }
}

示例响应

{
  "utm_source": [
    {
      "utm": "chatgpt.com",
      "views": 341
    },
    {
      "utm": "coolify.io",
      "views": 235
    },
    {
      "utm": "openalternative.co",
      "views": 89
    },
    {
      "utm": "facebook",
      "views": 28
    }
  ],
  "utm_medium": [
    {
      "utm": "cpc",
      "views": 28
    },
    {
      "utm": "referral",
      "views": 26
    }
  ],
  "utm_campaign": [
    {
      "utm": "website_analytics",
      "views": 28
    },
    {
      "utm": "navigation",
      "views": 16
    }
  ],
  "utm_term": [
    {
      "utm": "0_df65b6d7c8-e2c14ebdc7-59136105",
      "views": 1
    }
  ],
  "utm_content": [
    {
      "utm": "comparison-page",
      "views": 1
    },
    {
      "utm": "sidebar-cta",
      "views": 1
    }
  ]
}

实时

Previous Page

会话

Next Page

On this page

过滤器GET /api/reportsPOST /api/reportsGET /api/reports/:reportIdPOST /api/reports/:reportIdDELETE /api/reports/:reportIdPOST /api/reports/attributionPOST /api/reports/breakdownPOST /api/reports/funnelPOST /api/reports/goalPOST /api/reports/journeyPOST /api/reports/performancePOST /api/reports/retentionPOST /api/reports/revenuePOST /api/reports/utm