BI4Sight出海增长助手

概述

BI4Sight Ads Query

你好，我是 BI4Sight，你的出海增长搭档。

先看数据，再找机会，然后给出能执行的分析。把跨媒体、跨账户的投放数据交给我，我会把账户、消耗、趋势和广告层级表现整理成可核验的结果。

产品介绍

BI4Sight Ads Query 是面向出海投放团队的只读数据查询与报表分析 Skill。它通过 BI4Sight API 统一读取已授权媒体账户的数据，减少在多个平台之间切换和手工整理报表的成本。

当前 Skill 聚焦三类高频任务：

当前支持查询 Google Ads、Meta、TikTok、Snapchat、Kwai 投放数据；实际可见范围以 BI4Sight 账户授权和数据权限为准。

核心价值

• 统一查数：在一个入口查看跨媒体、跨账户投放数据。
• 高效报表：按账户、日期及广告层级快速生成结构化结果。
• 灵活下钻：从账户汇总进一步查看 Campaign、Ad Set 与 Ad 表现。
• 辅助决策：为预算分析、素材复盘、异常排查和增长策略提供可核验的数据基础。

适用场景

使用本 Skill 处理以下请求：

1. 账户盘点：列出已授权账户，按平台、名称/编号关键词、状态或账户 ID 筛选。
2. 消耗与效率查询：比较时间段、平台或账户的 spend、impressions、clicks、converts、CTR、CPC、CPM。
3. 报表与下钻：按平台/账户汇总，或进一步查看 campaign、ad set、ad；需要天粒度时增加日期维度。
4. 结果核验：返回原始聚合结果、分页信息和 totals，便于继续做 CPA、ROAS、空耗或异常分析。

典型对话入口

• “分析最近 7 天的投放表现，告诉我哪里值得加预算。”
• “列出所有 Meta 和 TikTok 账户，看看哪些账户受限。”
• “比较最近 14 天各媒体的消耗、点击和转化，按消耗降序排列。”
• “把最近 7 天的广告报告按天和 Ad 层级展开，找出高消耗低转化的广告。”

本 Skill 会提供数据查询基础，不会仅凭汇总指标编造因果结论。需要做策略、素材、盯盘或风险判断时，应基于查询结果明确区分事实、推断和待验证项。

Credential Setup（首次使用）

使用前请在 BI4Sight 官网 注册并获取/绑定你的专属 BI4Sight Key：

1. 打开注册入口：https://www.bi4sight.com
2. 登录后按 BI4Sight 控制台或市场的凭证配置说明取得 Key。当前客户端将 Key 作为 API 的 user-token 发送；如接口同时返回或要求租户信息，请一并准备 tenant-id。
3. 通过环境变量注入凭证（不要写入 Skill 文件、脚本、代码仓库或聊天记录）：

   export BI4SIGHT_TOKEN=<your-bi4sight-key>
   export BI4SIGHT_TENANT_ID=<your-tenant-id>  # 可选；按账号/接口要求提供

Key 失效时重新登录/刷新凭证并更新环境变量。脚本在缺少 Key 时会输出注册指引；BI4SIGHT_TENANT_ID 为可选项，只有在接口或租户隔离要求时才需要设置。

安全与使用说明

• 本 Skill 仅调用 BI4Sight 的查询接口：不会创建、发布、暂停、删除或修改广告，也不会调整预算。
• Key 仅从 BI4SIGHT_TOKEN 环境变量或 CLI 参数读取，作为 user-token 请求头发送；Skill 不把 Key 写入文件、缓存或日志，也不会把凭证发送到 BI4Sight 以外的服务。
• 默认只访问 https://api.bi4sight.com；只有用户明确配置 BI4SIGHT_BASE_URL 时才使用其他地址。首次接入建议使用可撤销、权限最小化的 Key 和测试账户。
• 不要把生产 Key 粘贴到对话、提交到代码仓库，或写入命令历史；发现泄露时应立即在 BI4Sight 控制台撤销并重新生成。
• 本 Skill 不包含自动化循环、后台任务或广告变更操作；每次查询都是一次由用户请求触发的无状态 HTTP 请求。
• 当前版本专注于只读数据查询与报表分析；具体可用能力以 Skill 页面和 BI4Sight 账户所开通的服务为准。
• 数据范围、媒体覆盖和可见账户以 API 实际返回为准；未返回的数据不补猜。
• 接口返回的是 BI4Sight 统计聚合数据，今天的数据可能存在同步延迟；涉及实时决策时应与媒体后台核对。

Service Configuration

The target is the BI4Sight online API gateway (forwarding to the AdManage.API microservice). The public registration and Key entry point is https://www.bi4sight.com; the API gateway is https://api.bi4sight.com.

Common request headers:

Content-Type: application/json
user-token: <BI4SIGHT_TOKEN>
tenant-id: <BI4SIGHT_TENANT_ID>

Quick Start (Script)

The skill ships CLI scripts and importable client libraries for Python and Node.js (standard library only, no third-party dependencies). Credentials come from the required BI4SIGHT_TOKEN and optional BI4SIGHT_TENANT_ID environment variables (a registration guide is shown when the Key is missing). The CLIs below wrap the libraries; for programmatic use see [Programmatic Usage (Library)](#programmatic-usage-library).

# 1. Account list query
python scripts/bi4sight_query.py accounts 
    --platform META --keyword "test" --page 1 --page-size 20

# 2. Account spend query (default metrics: spend,impressions,clicks,converts,ctr,cpc,cpm)
python scripts/bi4sight_query.py spend 
    --start 2026-08-01 --stop 2026-08-25 
    --platform GOOGLE --sort spend:desc --page 1 --page-size 20

# 3. Ads report query (fixed columns)
python scripts/bi4sight_query.py report 
    --start 2026-08-01 --stop 2026-08-25 
    --accounts 123456,234567 --by-date --page 1 --page-size 50

Output defaults to a table; add --format json for the full JSON payload (including pagination info and the totals row statistics).

Programmatic Usage (Library)

Prefer the standardized client library over hand-crafting HTTP requests from prose. Two language implementations share the same API surface; pick whichever your runtime supports.

Files:

• Python: scripts/bi4sight_client.py (standard library only, importable)
• Node.js: scripts/bi4sight-client.js (built-in http/https only, require-able)

Both expose a Bi4SightClient class and a Bi4SightError (business-level error with code/msg/requestId). Methods return the parsed data object; the report method returns the column-oriented structure (use the transposeReport helper to get row-oriented rows).

Python

import os
from bi4sight_client import (
    Bi4SightClient, Bi4SightError,
    REPORT_DIMENSIONS_BY_DATE, REPORT_METRICS,
)

client = Bi4SightClient(
    base_url="https://api.bi4sight.com",
    token=os.environ["BI4SIGHT_TOKEN"],
    tenant_id=os.environ.get("BI4SIGHT_TENANT_ID"),
)

# account list -> { list, statistics, pagination }
res = client.list_accounts(page=1, page_size=20, platform="META", keyword="test")

# account spend -> { list, statistics, pagination }
res = client.account_spend(start="2026-08-01", stop="2026-08-25",
                           metrics=["spend", "clicks"], sort="spend:desc")

# ads report (fixed columns) -> column-oriented { dimensions, metrics, statistics }
res = client.ads_report(start="2026-08-01", stop="2026-08-25",
                        accounts=[123456], by_date=True)
rows = client.transpose_report(
    res, REPORT_DIMENSIONS_BY_DATE, REPORT_METRICS
)  # row-oriented

try:
    data = client.list_accounts(platform="GOOGLE")
except Bi4SightError as e:
    print(f"business error: code={e.code} msg={e.msg}")

Node.js

const {
  Bi4SightClient, Bi4SightError, transposeReport,
  REPORT_DIMENSIONS_BY_DATE, REPORT_METRICS,
} = require('./bi4sight-client');

const client = new Bi4SightClient({
  baseUrl: process.env.BI4SIGHT_BASE_URL || 'https://api.bi4sight.com',
  token: process.env.BI4SIGHT_TOKEN,
  tenantId: process.env.BI4SIGHT_TENANT_ID,
});

// account list -> { list, statistics, pagination }
const list = await client.listAccounts({ page: 1, pageSize: 20, platform: 'META', keyword: 'test' });

// account spend -> { list, statistics, pagination }
const spend = await client.accountSpend({ start: '2026-08-01', stop: '2026-08-25', metrics: ['spend', 'clicks'], sort: 'spend:desc' });

// ads report (fixed columns) -> column-oriented { dimensions, metrics, statistics }
const report = await client.adsReport({ start: '2026-08-01', stop: '2026-08-25', accounts: [123456], byDate: true });
const rows = transposeReport(
  report, REPORT_DIMENSIONS_BY_DATE, REPORT_METRICS
);  // row-oriented

try {
  await client.listAccounts({ platform: 'GOOGLE' });
} catch (e) {
  if (e instanceof Bi4SightError) console.error(`business error: code=${e.code} msg=${e.msg}`);
}

Method reference

Common parameters: page/pageSize, platform, keyword, sort ("field:direction"). Date parameters (start/stop) accept YYYY-MM-DD strings (or datetime/Date). The report method accepts accounts, platform, level (campaign/adset/ad), byDate and returns the column-oriented structure; use transposeReport(data, dimensions, metrics) for row-oriented rows.

HTTP Specifications of the Three Queries

1. Account List Query

POST {BASE_URL}/api/axs/adaccount/list

Request body (all fields optional):

{
  "page": 1,
  "page_size": 20,
  "keyword": "account no or name",
  "keywords": ["kw1", "kw2"],
  "match_mode": "LIKE",
  "platform": "GOOGLE",
  "states": ["NORMAL"],
  "adaccount_ids": [123, 456],
  "owner_ids": [1001],
  "tag_id": 88,
  "company_id": 5,
  "sorting": { "field": "create_time", "direction": "desc" }
}

• platform values (string enums): GOOGLE / META / TIKTOK / SNAPCHAT / KWAI
• states values: NORMAL / ABNORMAL / MISS / LIMIT (restricted)
• match_mode: LIKE (fuzzy, default) / EXACT (exact); keywords takes precedence over keyword

Response rows in data.list[]: adaccount_id, adaccount_no, adaccount_name, adaccount_state, media_state, balance, currency, platform, owner_name, owner_team_name, company_name, time_zone, is_limit, create_time, authorized.

2. Account Spend Query

POST {BASE_URL}/api/axs/adaccount/stats

Request body:

{
  "page": 1,
  "page_size": 20,
  "date_range": { "start": "2026-08-01 00:00:00", "stop": "2026-08-25 23:59:59" },
  "metrics": ["spend", "impressions", "clicks", "converts", "ctr", "cpc", "cpm"],
  "platform": "GOOGLE",
  "keyword": "xxx",
  "sorting": { "field": "spend", "direction": "desc" }
}

• date_range is required; metrics is required (metric codes listed below)
• Common metric codes: spend, impressions, clicks, converts, ctr, cpc, cpm; conversion events look like action:omni_app_install, event values like action_value:omni_purchase, custom calculated columns like custom:cpi, custom:roas

Response rows in data.list[]: account_id, account_no, account_name, balance, currency, platform, account_state, plus a metrics dictionary (metric code → decimal value). data.statistics holds the totals of the current query.

3. Ads Report Query (Fixed Columns)

POST {BASE_URL}/api/axs/reporting/data

Fixed query columns (the convention of this skill, covering general ads analysis scenarios):

Request body (already wrapped by the script; reference for direct HTTP calls):

{
  "option": {
    "view_type": "TABLE",
    "metrics": ["spend", "impressions", "clicks", "converts", "ctr", "cpc", "cpm"],
    "dimensions": ["platform", "account_no", "account_name"],
    "sorting": { "field": "spend", "direction": "desc", "page": 1, "page_size": 50 },
    "sorting_fields": [
      { "name": "Spend", "field": "spend", "source_type": "METRIC" }
    ],
    "hidden_fields": "",
    "table_config": "",
    "is_level_show": false
  },
  "specs": {
    "selected_accounts": [123456],
    "account_dynamically_filter": null,
    "ad_dynamically_filter": null,
    "date_type": "",
    "start_date": "2026-08-01T00:00:00",
    "stop_date": "2026-08-25T23:59:59",
    "filters": []
  }
}

• Dimensions can be extended to ads levels: campaign_no/campaign_name, adset_no/adset_name, ad_no/ad_name
• date_type supports shortcuts: today, yesterday, last_7d, last_14d, last_30d, this_week, last_week, this_month, last_month, this_quarter, last_quarter, this_year, last_year; pass an empty string and use start_date/stop_date for a custom range
• selected_accounts and account_dynamically_filter are mutually exclusive; the former takes precedence

The response data is column-oriented: dimensions (dict: column name → value array), metrics (dict: metric name → decimal array), statistics (totals). The script transposes it into row-oriented tables automatically.

Response Conventions (Common to All Endpoints)

• The HTTP status code is usually 200 for business responses; business success is indicated by the code field
• code = 0 means success; any other value means failure — surface msg to the user
• Error codes: 40001 generic error, 40002 invalid argument, 40004 not found, 40006 domain error, 40007 business fault, 40010 auth failure (usually a missing or expired user-token)
• Envelope structure: { "code": 0, "msg": null, "data": {...}, "request_id": "..." }
• Paginated data structure: { "list": [...], "statistics": {...}, "pagination": { "page", "page_size", "page_count", "total_count" } }

Notes

• JSON serialization: enums are always passed as strings (e.g. "GOOGLE", "TABLE"); dates are standard DateTime strings
• Spend/report data is aggregated by the Statistics service from media platforms and may lag; treat the media platform as the source of truth for today's data
• When the Key/token expires (error code 40010), sign in again at https://www.bi4sight.com, obtain or refresh the Key, and update BI4SIGHT_TOKEN; if your account uses tenant isolation, also update BI4SIGHT_TENANT_ID

Files

scripts/
├── bi4sight_client.py     # Python client library (importable)
├── bi4sight_query.py      # Python CLI (wraps the library)
├── bi4sight-client.js     # Node.js client library (require-able)
└── bi4sight-query.js      # Node.js CLI (wraps the library)
references/
└── api-reference.md       # Detailed endpoint field documentation

The CLIs share the same flags across both languages, e.g. python bi4sight_query.py spend ... and node bi4sight-query.js spend ....

Recommended analysis workflow

When the user asks for an analysis rather than a raw export, follow this sequence:

1. Clarify the date range, media scope, account scope and desired grain (account, day, campaign, ad set or ad).
2. Query the smallest useful data set first; use accounts to discover IDs and spend for account-level comparison.
3. Use report --by-date or report --level ... --by-date only when a time trend or drill-down is needed.
4. State the currency, aggregation grain, row count and data freshness before interpreting results.
5. Base recommendations on returned metrics; label calculations such as CPA/ROAS and any causal explanation as derived or requiring verification.

The query results can be used as a structured data foundation for reporting, diagnostics and optimization workflows.

Reference

Detailed endpoint field documentation: [references/api-reference.md](references/api-reference.md).