Analytics

Product analytics: track, identify, funnels and cohorts.

Overview

Base path: https://api.infrai.cc/v1/analytics

Auth header: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/analytics capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/analytics/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

Methods

analytics.track

POST /v1/analytics/track

Track one or more analytics events.

Parameters

Name	Type	Required	Description
`event`	`string`	Required	Event name.
`distinct_id`	`string`	Required	Stable id of the acting user.
`properties`	`Record<string, unknown>`	Optional	Arbitrary event properties.

Returns

{ ok, accepted }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/track \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "checkout_completed", "distinct_id": "user_42", "properties": {"amount": 19.99}}'

analytics.identify

POST /v1/analytics/identify

Associate traits with a distinct id.

Parameters

Name	Type	Required	Description
`distinct_id`	`string`	Required	Stable id of the acting user.
`user_id`	`string`	Optional	Id of the connecting user.
`traits`	`Record<string, unknown>`	Optional	User traits to set.

Returns

{ ok: boolean }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/identify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id": "..."}'

analytics.alias

POST /v1/analytics/alias

合并身份别名

Parameters

Name	Type	Required	Description
`old_id`	`string`	Required	要合并的来源 distinct_id（例如匿名 id）。
`new_id`	`string`	Required	合并目标的规范 distinct_id。
`idempotency_key`	`string`	Optional	可选幂等键，确保重复请求只生效一次。

Returns

AliasResult { merged: boolean }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/alias \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"old_id": "...", "new_id": "..."}'

analytics.batch

POST /v1/analytics/batch

批量上报事件

Parameters

Name	Type	Required	Description
`events`	`TrackEvent[]`	Required	至多 1000 条 TrackEvent 事件，每条事件自带幂等键。

Returns

{ ok: boolean, accepted: number }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/batch \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": []}'

analytics.group

POST /v1/analytics/group

关联群组

Parameters

Name	Type	Required	Description
`distinct_id`	`string`	Required	要关联到群组的用户 distinct_id。
`group_type`	`string`	Required	群组维度，例如 company / team。
`group_key`	`string`	Required	在 group_type 下的群组标识符。
`traits`	`Record<string, unknown>`	Optional	可选的群组档案属性。
`idempotency_key`	`string`	Optional	可选幂等键，确保重复请求只生效一次。

Returns

{ ok: boolean }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/group \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id": "...", "group_type": "...", "group_key": "..."}'

analytics.dashboard.create

POST /v1/analytics/dashboard/create

创建仪表盘

Parameters

Name	Type	Required	Description
`name`	`string`	Required	仪表盘名称。
`queries`	`object[]`	Required	组成仪表盘的已保存查询列表。
`idempotency_key`	`string`	Optional	可选幂等键，确保重复请求只生效一次。

Returns

Dashboard

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/dashboard/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "...", "queries": []}'

analytics.dashboard.get

GET /v1/analytics/dashboard/get/{dashboard_id}

获取仪表盘

Parameters

Name	Type	Required	Description
`dashboard_id`	`string`	Required	仪表盘 id。

Returns

Dashboard

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/analytics/dashboard/get/DASHBOARD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

analytics.dashboard.list

GET /v1/analytics/dashboard/list

列出仪表盘

Parameters

Name	Type	Required	Description
`cursor`	`string`	Optional	来自上一页 next_cursor 的不透明游标。
`limit`	`number`	Optional	本页返回的最大条数。

Returns

{ items: Dashboard[], next_cursor?: string }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/analytics/dashboard/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

analytics.dashboard.delete

DELETE /v1/analytics/dashboard/delete/{dashboard_id}

删除仪表盘

Parameters

Name	Type	Required	Description
`dashboard_id`	`string`	Required	要删除的仪表盘 id。
`idempotency_key`	`string`	Optional	可选幂等键，确保重复请求只生效一次。

Returns

{ ok: boolean }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/analytics/dashboard/delete/DASHBOARD_ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

analytics.query.events

POST /v1/analytics/query/events

查询原始事件

Parameters

Name	Type	Required	Description
`since`	`string`	Required	时间窗口起点（含）。
`until`	`string`	Required	时间窗口终点（不含）。
`filter`	`Record<string, unknown>`	Optional	可选属性过滤（键/值匹配）。
`limit`	`number`	Optional	本页返回的最大条数（1-1000，默认 1000）。
`cursor`	`string`	Optional	来自上一页 next_cursor 的不透明游标。

Returns

EventQueryResult { events: object[], next_cursor?: string }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/query/events \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"since": "...", "until": "..."}'

analytics.query.retention

POST /v1/analytics/query/retention

查询留存

Parameters

Name	Type	Required	Description
`born_event`	`string`	Required	定义群组归属（第 0 天）的事件。
`return_event`	`string`	Required	其再次发生用于衡量留存的事件。
`since`	`string`	Required	时间窗口起点。
`until`	`string`	Required	时间窗口终点。
`interval`	`string`	Optional	分桶周期（默认 day）。

Returns

RetentionResult { matrix: number[][] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/query/retention \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"born_event": "...", "return_event": "...", "since": "...", "until": "..."}'

analytics.query.path

POST /v1/analytics/query/path

查询行为路径

Parameters

Name	Type	Required	Description
`start_event`	`string`	Required	路径树展开的根事件。
`since`	`string`	Required	时间窗口起点。
`until`	`string`	Required	时间窗口终点。
`max_depth`	`number`	Optional	路径树最大深度（1-20，默认 5）。

Returns

PathResult { root: string, children: object[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/analytics/query/path \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_event": "...", "since": "...", "until": "..."}'

All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

Capability	Endpoint	Description
`analytics.alias`	`POST /v1/analytics/alias`	Rename or merge an anonymous distinct_id (old_id) into a known identity (new_id).
`analytics.batch`	`POST /v1/analytics/batch`	Ingest up to 1000 TrackEvent events in a single call (idempotency is per-event).
`analytics.dashboard.create`	`POST /v1/analytics/dashboard/create`	Assemble a dashboard from saved queries and return the Dashboard.
`analytics.dashboard.delete`	`DELETE /v1/analytics/dashboard/delete/{dashboard_id}`	Delete a dashboard by dashboard_id (idempotent).
`analytics.dashboard.get`	`GET /v1/analytics/dashboard/get/{dashboard_id}`	Get a single dashboard by dashboard_id.
`analytics.dashboard.list`	`GET /v1/analytics/dashboard/list`	List all dashboards on the account with cursor pagination.
`analytics.group`	`POST /v1/analytics/group`	Associate a distinct_id with a group (organization/team/account) for B2B account-level aggregation.
`analytics.identify`	`POST /v1/analytics/identify`	Set profile traits on a distinct_id, optionally merging a prior id via alias_for.
`analytics.query.events`	`POST /v1/analytics/query/events`	Query raw events within a time window, with attribute filters and cursor pagination.
`analytics.query.path`	`POST /v1/analytics/query/path`	Build behavioral path/sequence trees rooted at a start event within a time window.
`analytics.query.retention`	`POST /v1/analytics/query/retention`	Compute a retention matrix bucketed by period from a born event to a return event.
`analytics.track`	`POST /v1/analytics/track`	Ingest a single product analytics event with properties for a distinct user; idempotent.

End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) analytics.track
curl -X POST https://api.infrai.cc/v1/analytics/track \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "checkout_completed", "distinct_id": "user_42", "properties": {"amount": 19.99}}'

# 3) analytics.identify
curl -X POST https://api.infrai.cc/v1/analytics/identify \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id": "..."}'

# 4) analytics.alias
curl -X POST https://api.infrai.cc/v1/analytics/alias \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"old_id": "...", "new_id": "..."}'

# 5) analytics.batch
curl -X POST https://api.infrai.cc/v1/analytics/batch \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": []}'

# 6) analytics.group
curl -X POST https://api.infrai.cc/v1/analytics/group \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"distinct_id": "...", "group_type": "...", "group_key": "..."}'

# 7) analytics.dashboard.create
curl -X POST https://api.infrai.cc/v1/analytics/dashboard/create \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "...", "queries": []}'