API docs by Redocly

增长数据平台 API (1.0.0-proposed)

下载 OpenAPI 规范:

合同状态

这是供团队评审的 proposed v1 合同。文档站点已公开发布，但本次发布不包含 Data API 运行时。

鉴权

所有接口都使用 Bearer API Key。数据上报方使用限定到来源的 ingest:{source} Key；Dashboard 和其他只读消费者使用独立的 query:read Key。入库 Key 不能查询数据，查询 Key 也不能写入数据。

数据同步流程

  1. 使用来源、数据流、Schema 版本、游标和覆盖范围创建一个 Sync Run。
  2. 按顺序上传一个或多个批次；每个批次都按内容寻址，并支持幂等重试。
  3. 提交 Sync Run，同时声明预期批次数、记录数和下一个游标。
  4. 轮询运行状态，直到进入 PUBLISHED 或终态失败。只有原子发布成功后，来源游标才会推进。

数据查询流程

  1. 读取数据目录，发现可查询的数据集、维度、指标和过滤条件。
  2. 首次查询使用 revision: latest，并保留响应中的数字 data_revision。
  3. 同一页面的后续查询和游标翻页都使用这个数字 revision，确保整页数据来自同一版本。

十进制数在 HTTP 中编码为字符串。缺失值保持为 null，绝不改写为零。日期与时间口径必须遵循各 Dataset 描述。

数据同步

由独立部署的 Collector 和 Connector 通过原子、幂等的接口同步数据。

创建或恢复一个同步运行

为一个来源、数据流和数据范围创建 OPEN 状态的 Sync Run。使用相同幂等键和指纹重试时返回已有运行；同一幂等键对应不同指纹时返回冲突。

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
source
required
string
Enum: "qianchuan" "shipinhao" "material" "control_plane" "execution" "economics"
stream
required
string
Enum: "account_state" "product_state" "plan_state" "plan_material_binding" "plan_daily_performance" "material_daily_performance" "promotion_order_lifecycle" "long_term_plan_state" "long_term_plan_daily" "business_material" "platform_material_registry" "strategy_registry" "allocation_state" "strategy_binding" "sku_economics_policy"
source_scope_id
required
string [ 1 .. 256 ] characters
mode
required
string
Enum: "incremental" "reconciliation" "repair" "backfill" "bootstrap"
schema_version
required
string non-empty
cursor_before
required
object or null
required
object (Coverage)
time_basis
required
string (TimeBasis)
Enum: "acquisition_date_natural_day" "natural_day_daily_metrics" "order_creation_date_lifecycle_total" "observation_time_state" "effective_time_state" "source_window_cumulative"
timezone
required
string
Enum: "Asia/Shanghai" "UTC"
window_start
string or null <date>
window_end
string or null <date>
completeness
required
string
Enum: "delta" "partial" "complete_replacement"
idempotency_key
required
string [ 1 .. 256 ] characters

Responses

Response Schema: application/json
run_id
required
string <uuid>
state
required
string
Enum: "OPEN" "PROCESSING" "PUBLISHED" "REJECTED" "ABORTED" "EXPIRED"
source
required
string
Enum: "qianchuan" "shipinhao" "material" "control_plane" "execution" "economics"
stream
required
string
Enum: "account_state" "product_state" "plan_state" "plan_material_binding" "plan_daily_performance" "material_daily_performance" "promotion_order_lifecycle" "long_term_plan_state" "long_term_plan_daily" "business_material" "platform_material_registry" "strategy_registry" "allocation_state" "strategy_binding" "sku_economics_policy"
schema_version
required
string
expires_at
required
string <date-time>
data_revision
string or null^[0-9]+$
cursor_after
object or null
ErrorEnvelope (object) or null
Any of
code
required
string
message
required
string
request_id
required
string
details
object or null
retry_after_seconds
integer or null >= 0
required
object
max_batch_records
required
integer
Value: 1000
max_batch_bytes
required
integer
Value: 5242880
max_run_batches
required
integer
Value: 200
max_run_records
required
integer
Value: 200000
max_run_bytes
required
integer
Value: 262144000
Response Schema: application/json
run_id
required
string <uuid>
state
required
string
Enum: "OPEN" "PROCESSING" "PUBLISHED" "REJECTED" "ABORTED" "EXPIRED"
source
required
string
Enum: "qianchuan" "shipinhao" "material" "control_plane" "execution" "economics"
stream
required
string
Enum: "account_state" "product_state" "plan_state" "plan_material_binding" "plan_daily_performance" "material_daily_performance" "promotion_order_lifecycle" "long_term_plan_state" "long_term_plan_daily" "business_material" "platform_material_registry" "strategy_registry" "allocation_state" "strategy_binding" "sku_economics_policy"
schema_version
required
string
expires_at
required
string <date-time>
data_revision
string or null^[0-9]+$
cursor_after
object or null
ErrorEnvelope (object) or null
Any of
code
required
string
message
required
string
request_id
required
string
details
object or null
retry_after_seconds
integer or null >= 0
required
object
max_batch_records
required
integer
Value: 1000
max_batch_bytes
required
integer
Value: 5242880
max_run_batches
required
integer
Value: 200
max_run_records
required
integer
Value: 200000
max_run_bytes
required
integer
Value: 262144000

Request samples

Content type
application/json
{
  • "source": "qianchuan",
  • "stream": "plan_daily_performance",
  • "source_scope_id": "shop_demo:advertiser_demo",
  • "mode": "incremental",
  • "schema_version": "qianchuan.plan-daily.v1",
  • "cursor_before": {
    • "window_end": "2026-08-04"
    },
  • "coverage": {
    • "time_basis": "acquisition_date_natural_day",
    • "timezone": "Asia/Shanghai",
    • "window_start": "2026-07-06",
    • "window_end": "2026-08-04",
    • "completeness": "complete_replacement"
    },
  • "idempotency_key": "qc:advertiser_demo:20260805T010000Z"
}

Response samples

Content type
application/json
{
  • "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  • "state": "OPEN",
  • "source": "qianchuan",
  • "stream": "account_state",
  • "schema_version": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "data_revision": "string",
  • "cursor_after": { },
  • "error": {
    • "code": "string",
    • "message": "string",
    • "request_id": "string",
    • "details": { },
    • "retry_after_seconds": 0
    },
  • "limits": {
    • "max_batch_records": 1000,
    • "max_batch_bytes": 5242880,
    • "max_run_batches": 200,
    • "max_run_records": 200000,
    • "max_run_bytes": 262144000
    }
}

暂存一个有序记录批次

使用严格的来源 Schema 校验记录信封，并暂存一个按内容寻址的批次。使用相同 sequence 和 payload hash 重试时幂等成功；同一 sequence 对应不同内容时拒绝写入。

Authorizations:
ApiKeyAuth
path Parameters
run_id
required
string <uuid>
sequence
required
integer [ 1 .. 200 ]
Request Body schema: application/json
required
sequence
required
integer [ 1 .. 200 ]
record_count
required
integer [ 0 .. 1000 ]
payload_sha256
required
string^[0-9a-f]{64}$
required
Array of objects (record_envelope_schema) <= 1000 items
Array (<= 1000 items)
source
required
any
Enum: "qianchuan" "shipinhao" "material" "control_plane" "execution" "economics"
stream
required
any
Enum: "account_state" "product_state" "plan_state" "plan_material_binding" "plan_daily_performance" "material_daily_performance" "promotion_order_lifecycle" "long_term_plan_state" "long_term_plan_daily" "business_material" "platform_material_registry" "strategy_registry" "allocation_state" "strategy_binding" "sku_economics_policy"
source_record_id
required
string [ 1 .. 512 ] characters
operation
required
any
Enum: "upsert" "tombstone"
event_time
required
string or null
source_updated_at
required
string or null <date-time>
observed_at
required
string <date-time>
schema_version
required
string non-empty
required
object

validated by schema_version payload_schema in this registry

Responses

Request samples

Content type
application/json
{
  • "sequence": 1,
  • "record_count": 1000,
  • "payload_sha256": "string",
  • "records": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "request_id": "string",
  • "details": { },
  • "retry_after_seconds": 0
}

提交同步运行并开始处理

冻结完整批次集合，并将运行推进到 PROCESSING。Canonical 事实、Mart、游标推进和已发布 data revision 会在同一个事务中原子可见。

Authorizations:
ApiKeyAuth
path Parameters
run_id
required
string <uuid>
Request Body schema: application/json
required
expected_batch_count
required
integer [ 0 .. 200 ]
expected_record_count
required
integer [ 0 .. 200000 ]
run_payload_sha256
required
string^[0-9a-f]{64}$
cursor_after
required
object or null

Responses

Response Schema: application/json
run_id
required
string <uuid>
state
required
string
Enum: "OPEN" "PROCESSING" "PUBLISHED" "REJECTED" "ABORTED" "EXPIRED"
source
required
string
Enum: "qianchuan" "shipinhao" "material" "control_plane" "execution" "economics"
stream
required
string
Enum: "account_state" "product_state" "plan_state" "plan_material_binding" "plan_daily_performance" "material_daily_performance" "promotion_order_lifecycle" "long_term_plan_state" "long_term_plan_daily" "business_material" "platform_material_registry" "strategy_registry" "allocation_state" "strategy_binding" "sku_economics_policy"
schema_version
required
string
expires_at
required
string <date-time>
data_revision
string or null^[0-9]+$
cursor_after
object or null
ErrorEnvelope (object) or null
Any of
code
required
string
message
required
string
request_id
required
string
details
object or null
retry_after_seconds
integer or null >= 0
required
object
max_batch_records
required
integer
Value: 1000
max_batch_bytes
required
integer
Value: 5242880
max_run_batches
required
integer
Value: 200
max_run_records
required
integer
Value: 200000
max_run_bytes
required
integer
Value: 262144000

Request samples

Content type
application/json
{
  • "expected_batch_count": 200,
  • "expected_record_count": 200000,
  • "run_payload_sha256": "string",
  • "cursor_after": { }
}

Response samples

Content type
application/json
{
  • "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  • "state": "OPEN",
  • "source": "qianchuan",
  • "stream": "account_state",
  • "schema_version": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "data_revision": "string",
  • "cursor_after": { },
  • "error": {
    • "code": "string",
    • "message": "string",
    • "request_id": "string",
    • "details": { },
    • "retry_after_seconds": 0
    },
  • "limits": {
    • "max_batch_records": 1000,
    • "max_batch_bytes": 5242880,
    • "max_run_batches": 200,
    • "max_run_records": 200000,
    • "max_run_bytes": 262144000
    }
}

中止一个 OPEN 同步运行

停止尚未提交的运行并释放暂存数据。对终态运行重复调用时幂等返回；该操作不会回滚已经发布的数据。

Authorizations:
ApiKeyAuth
path Parameters
run_id
required
string <uuid>

Responses

Response Schema: application/json
run_id
required
string <uuid>
state
required
string
Enum: "OPEN" "PROCESSING" "PUBLISHED" "REJECTED" "ABORTED" "EXPIRED"
source
required
string
Enum: "qianchuan" "shipinhao" "material" "control_plane" "execution" "economics"
stream
required
string
Enum: "account_state" "product_state" "plan_state" "plan_material_binding" "plan_daily_performance" "material_daily_performance" "promotion_order_lifecycle" "long_term_plan_state" "long_term_plan_daily" "business_material" "platform_material_registry" "strategy_registry" "allocation_state" "strategy_binding" "sku_economics_policy"
schema_version
required
string
expires_at
required
string <date-time>
data_revision
string or null^[0-9]+$
cursor_after
object or null
ErrorEnvelope (object) or null
Any of
code
required
string
message
required
string
request_id
required
string
details
object or null
retry_after_seconds
integer or null >= 0
required
object
max_batch_records
required
integer
Value: 1000
max_batch_bytes
required
integer
Value: 5242880
max_run_batches
required
integer
Value: 200
max_run_records
required
integer
Value: 200000
max_run_bytes
required
integer
Value: 262144000

Response samples

Content type
application/json
{
  • "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  • "state": "OPEN",
  • "source": "qianchuan",
  • "stream": "account_state",
  • "schema_version": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "data_revision": "string",
  • "cursor_after": { },
  • "error": {
    • "code": "string",
    • "message": "string",
    • "request_id": "string",
    • "details": { },
    • "retry_after_seconds": 0
    },
  • "limits": {
    • "max_batch_records": 1000,
    • "max_batch_bytes": 5242880,
    • "max_run_batches": 200,
    • "max_run_records": 200000,
    • "max_run_bytes": 262144000
    }
}

查询同步运行状态

返回调用方拥有的 Sync Run 当前生命周期状态、终态错误、已发布 data revision 和游标结果。

Authorizations:
ApiKeyAuth
path Parameters
run_id
required
string <uuid>

Responses

Response Schema: application/json
run_id
required
string <uuid>
state
required
string
Enum: "OPEN" "PROCESSING" "PUBLISHED" "REJECTED" "ABORTED" "EXPIRED"
source
required
string
Enum: "qianchuan" "shipinhao" "material" "control_plane" "execution" "economics"
stream
required
string
Enum: "account_state" "product_state" "plan_state" "plan_material_binding" "plan_daily_performance" "material_daily_performance" "promotion_order_lifecycle" "long_term_plan_state" "long_term_plan_daily" "business_material" "platform_material_registry" "strategy_registry" "allocation_state" "strategy_binding" "sku_economics_policy"
schema_version
required
string
expires_at
required
string <date-time>
data_revision
string or null^[0-9]+$
cursor_after
object or null
ErrorEnvelope (object) or null
Any of
code
required
string
message
required
string
request_id
required
string
details
object or null
retry_after_seconds
integer or null >= 0
required
object
max_batch_records
required
integer
Value: 1000
max_batch_bytes
required
integer
Value: 5242880
max_run_batches
required
integer
Value: 200
max_run_records
required
integer
Value: 200000
max_run_bytes
required
integer
Value: 262144000

Response samples

Content type
application/json
{
  • "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  • "state": "OPEN",
  • "source": "qianchuan",
  • "stream": "account_state",
  • "schema_version": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "data_revision": "string",
  • "cursor_after": { },
  • "error": {
    • "code": "string",
    • "message": "string",
    • "request_id": "string",
    • "details": { },
    • "retry_after_seconds": 0
    },
  • "limits": {
    • "max_batch_records": 1000,
    • "max_batch_bytes": 5242880,
    • "max_run_batches": 200,
    • "max_run_records": 200000,
    • "max_run_bytes": 262144000
    }
}

数据目录

提供机器可读的 Dataset、字段、指标、粒度和过滤条件合同。

列出可查询的数据集

返回所有公开 Dataset 的描述，包括数据粒度、字段、指标、维度、时间语义、聚合方式和支持的过滤条件。

Authorizations:
ApiKeyAuth

Responses

Response Schema: application/json
required
Array of objects (DatasetDescriptor)
Array
dataset
required
string
schema_version
required
integer >= 1
grain
required
Array of strings
default_time_field
required
string or null
dimensions
required
Array of strings
metrics
required
Array of strings
required
Array of objects (FieldDescriptor)
supported_filters
required
Array of strings
Items Enum: "eq" "in" "between"
max_time_range_days
required
integer or null

Response samples

Content type
application/json
{
  • "datasets": [
    • {
      }
    ]
}

获取单个数据集描述

返回一个 Dataset 的权威查询合同。客户端应根据该描述构建查询，不应硬编码数据库列。

Authorizations:
ApiKeyAuth
path Parameters
dataset_id
required
string

Responses

Response Schema: application/json
dataset
required
string
schema_version
required
integer >= 1
grain
required
Array of strings
default_time_field
required
string or null
dimensions
required
Array of strings
metrics
required
Array of strings
required
Array of objects (FieldDescriptor)
Array
name
required
string
role
required
any
Enum: "dimension" "metric"
type
required
string
unit
string or null
TimeBasis (string) or "row.time_basis" (any) or null
timezone
string or null
Enum: "Asia/Shanghai" "UTC" null
actuality
string or null
Enum: "actual" "estimated" "mixed" null
nullable
required
boolean
null_semantics
required
string
allowed_aggregations
required
Array of any
Items Enum: "sum" "min" "max" "count" "none"
supported_filters
required
Array of strings
Items Enum: "eq" "in" "between"
max_time_range_days
required
integer or null

Response samples

Content type
application/json
{
  • "dataset": "string",
  • "schema_version": 1,
  • "grain": [
    • "string"
    ],
  • "default_time_field": "string",
  • "dimensions": [
    • "string"
    ],
  • "metrics": [
    • "string"
    ],
  • "fields": [
    • {
      }
    ],
  • "supported_filters": [
    • "eq"
    ],
  • "max_time_range_days": 0
}

数据源状态

查看已发布数据的覆盖范围和新鲜度。

列出数据源新鲜度摘要

按已知来源、数据范围和 Dataset 组合，返回最近发布 revision、观察时间、新鲜度和覆盖状态。

Authorizations:
ApiKeyAuth

Responses

Response Schema: application/json
required
Array of objects (SourceFreshness)
Array
source
required
string
data_revision
required
string or null^[0-9]+$
required
Array of objects (SourceScopeFreshness)

Response samples

Content type
application/json
{
  • "sources": [
    • {
      }
    ]
}

获取单个数据源的新鲜度

返回一个已知数据源的新鲜度和覆盖详情。来源采集周期与平台处理延迟是两个独立指标。

Authorizations:
ApiKeyAuth
path Parameters
source
required
string

Responses

Response Schema: application/json
source
required
string
data_revision
required
string or null^[0-9]+$
required
Array of objects (SourceScopeFreshness)
Array
source_scope_id
required
string
last_observed_at
required
string or null <date-time>
last_published_at
required
string or null <date-time>
freshness_status
required
string
Enum: "fresh" "stale" "unknown"

Response samples

Content type
application/json
{
  • "source": "string",
  • "data_revision": "string",
  • "scopes": [
    • {
      }
    ]
}

数据查询

在固定 revision 上，通过字段白名单查询公开 Dataset。

在固定 revision 上查询数据集

执行受字段白名单约束的分组、总计或明细查询。dimensions: [] 表示由服务端计算总计；metrics: [] 表示查询明细行。首次使用 revision: latest，后续查询和游标翻页固定使用响应中的数字 revision。

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
dataset
required
string
required
"latest" (any) or string
One of
any ("latest")
dimensions
required
Array of strings unique
metrics
required
Array of strings unique
Array of objects (Filter)
Array
field
required
string
op
required
string
Enum: "eq" "in" "between"
value
required
any
object (TimeRange)
start
required
string <date>
end
required
string <date>
Array of objects (Sort)
Array
field
required
string
direction
required
string
Enum: "asc" "desc"
limit
integer [ 1 .. 1000 ]
Default: 200
cursor
string or null

Responses

Response Schema: application/json
contract_version
required
any
Value: "growth-data-platform.query.v1"
dataset
required
string
schema_version
required
integer
data_revision
required
string^[0-9]+$
required
Array of objects (QueryItem)
Array
required
object (MetricStatus)
property name*
additional property
any
next_cursor
required
string or null
required
Array of objects (QueryFreshness)
Array
source
required
string
observed_at
required
string or null <date-time>
status
required
any
Enum: "fresh" "stale" "unknown"
required
object (QueryCoverage)
status
required
any
Enum: "complete" "partial" "unknown"
covered_object_count
required
integer >= 0
expected_object_count
integer or null >= 0
reason_code
string or null
warnings
required
Array of objects

Request samples

Content type
application/json
{
  • "dataset": "strategy_daily",
  • "revision": "latest",
  • "dimensions": [
    • "event_date",
    • "platform",
    • "strategy_id",
    • "time_basis"
    ],
  • "metrics": [
    • "actual_spend_cny",
    • "expected_final_contribution_profit_cny"
    ],
  • "filters": [
    • {
      }
    ],
  • "time_range": {
    • "start": "2026-08-01",
    • "end": "2026-08-05"
    },
  • "order_by": [
    • {
      }
    ],
  • "limit": 200
}

Response samples

Content type
application/json
{
  • "contract_version": "growth-data-platform.query.v1",
  • "dataset": "strategy_daily",
  • "schema_version": 1,
  • "data_revision": "42",
  • "items": [
    • {
      }
    ],
  • "next_cursor": null,
  • "freshness": [
    • {
      }
    ],
  • "coverage": {
    • "status": "complete",
    • "covered_object_count": 3,
    • "expected_object_count": 3,
    • "reason_code": null
    },
  • "warnings": [ ]
}