shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsAPI key required

B站三连广告-报表

Bilibili Sanlian Ads delivery reporting. Use the custom report endpoint to query spend, impressions, clicks, conversions and other delivery metrics across dimensions - account, campaign, unit and creative for the legacy structure, or project and media for creative-driven delivery 2.0 - with date or hour granularity. 中文触发词：报表、数据、消耗、花费、曝光、点击、转化、投放数据、自定义报表、看数据、跑量情况。

personAuthor: user_b0010d5chubcommunity
downloadDownload package

Bilibili Sanlian Ads — Delivery Reporting (投放报表)

One endpoint, POST /open_api/report/v3/custom/query, answers every delivery-performance question: pick dimensions, pick metrics, pick a date, optionally filter, and read the rows back.

It is the only source of delivery metrics in this skill set. The ad management and delivery endpoints deliberately return no spend, impression or click data.

Usage Rules

  • Confirm a valid access_token and advertiser account_id first; use bilibili-sanlian-ads when either is missing.
  • POST https://cm.bilibili.com/takumi/api/open_api/report/v3/custom/query with Authorization: Bearer {access_token}, Content-Type: application/json, and X-Call-Source: sanlian-skills.
  • Open references/807_自定义报表.md before composing a query. The dimension and metric names are exact strings; an unknown metric is rejected outright. Never guess a metric name or translate one from another ad platform.
  • Follow the sequential-call and error-stop discipline in bilibili-sanlian-ads. Query one day or page at a time, and do not start the next request until the previous one has completed and its response has been checked.
  • Resolve ambiguous language such as “昨天”, “最近”, “跑得好” or “转化” into an exact date/time zone, metric and object scope before calling. For a range or paginated result, estimate the day/page call plan and confirm it before starting.
  • The endpoint only returns rows that had spend. A missing row means no spend, not an error and not a gap to retry.

Reporting Scope And Object Modes

For account-level totals, pass account_id and do not add campaign/unit/creative/project/media dimensions or filters. One account-level query returns data from both legacy delivery and creative-driven 2.0 delivery.

When object-level dimensions or filters are present, the request switches mode based on the object IDs you ask for, and the two modes have different metric vocabularies.

| | Legacy mode | Creative-driven 2.0 mode | |---|---|---| | Triggered by | campaign_id, unit_id or creative_id in dimensions or filters[].field | promotion_id or media_id appearing in dimensions or filters[].field | | Metric set | The legacy metric set | A separate list of 116 base metrics | | Derived metrics | Available | Not available — no cost_per_*, no *_rate, no *_roi |

Rules that follow from this:

  • Never mix the two. Project/media dimensions and campaign/unit/creative dimensions in one query return 系统繁忙. Run two queries.
  • Requesting a metric outside the active mode's list returns 指标 [xxx] 不存在. That error means wrong mode or wrong name — not a transient failure, so do not retry it.
  • In 2.0 mode, compute ratios yourself from the absolute metrics. The platform will not return them.

Constraints That Shape The Query Loop

  • One day per request. start_time and end_time must be the same YYYY-MM-DD. A date range means looping day by day, strictly sequentially and never fanned out. Report progress between long ranges and stop on the first failed day/page instead of skipping it.
  • At most 100 IDs per filter item. filters[].values cannot be empty once the filter item is present. Split larger ID sets across requests.
  • Date or hour granularity is selectable; hour granularity multiplies row count, so page accordingly.

Money Precision

Amounts come in two flavours, and picking the wrong one silently loses precision:

  • Fields without a suffix are in yuan.
  • Fields with the _milli suffix return the raw milli-cent value, where 1 yuan = 100000.

For display, use the yuan fields. For reconciliation, billing checks or anything that must add up exactly, use _milli and do the arithmetic in integers.

Which Skill Answers The Question

  • "How much did we spend / how did the ads perform" → this skill.
  • "What is the account balance / budget / cash flow" → bilibili-sanlian-ads-account-finance. Report spend and account finance are different systems and will not reconcile field-for-field.

Reading Responses And Errors

Business success or failure is carried in the response body, not the HTTP status.

When a query fails, check in this order before changing anything: are start_time and end_time both present, correctly formatted, and the same day; are all required fields present; is every metric in the active mode's list; are the dimensions all from one mode.

On any error or unclear outcome, stop the date/page loop and run the main skill's cold re-check and support-packet workflow. Do not permute dimensions and metrics to see which combination the API accepts, and do not skip the failed request.

Source Document Index

Synced from mapi/product/docs/开发者中心/MAPI接入/投放报表/. doc_id matches the article ID on the developer site.

| Source document | Local reference | Endpoint | |---|---|---| | 投放报表/自定义报表 (807) | references/807_自定义报表.md | POST /open_api/report/v3/custom/query — full dimension and metric lists for both modes |