Adsup

API 与 MCP

在你自己的代码或 AI Agent 中搜索开放网络广告、查询广告主 / 媒体 / 广告网络，并提交按需抓取。

最近更新: 2026-11-07

Adsup.ai API 提供与网页端相同的数据：我们爬虫捕获的广告、广告主 / 媒体 / 广告网络档案、覆盖账本以及按需抓取。每个操作也都是我们 MCP 服务上的一个工具，Claude 等 AI Agent 可以直接调用。

机器可读的接口描述见 /api/v1/openapi.json（OpenAPI 3.1）。

访问与密钥

API 与 MCP 访问包含在 Pro 和 Team 套餐中。在 设置 → API 密钥 创建密钥，并在每个请求中带上：

curl -H "Authorization: Bearer sk_your_key" \
  "https://adsup.ai/api/v1/ads?q=vpn&geos=US,DE&pageSize=20"

密钥属于你的账号，删除即立即失效。浏览器 Cookie 不能用于调用 API。

积分

调用会消耗套餐中的积分：Pro 每月 5,000 积分，Team 每月 50,000 积分（年付一次性发放全年积分）。余额、本月用量和每次调用的单价可在 API 密钥页面或 GET /api/v1/me/usage 查看。

调用积分
广告搜索（一页，最多 50 条）1
广告详情1
广告主 / 媒体 / 广告网络档案1
覆盖账本1
抓取请求状态1
提交按需抓取20
GET /api/v1/me/usage、MCP 握手与工具列表0

失败的调用（任何 4xx / 5xx，包括“未找到”）会自动退还积分。每个响应都带有 X-Credits-Charged 头。

限额

  • 限流： 每个密钥每分钟 60 次请求。超出返回 HTTP 429 并带 Retry-After。每个响应都带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。
  • 历史深度： Pro 可查最近 180 天，Team 可查全部历史。超出范围的日期条件会被收窄，并在 meta.limited 中注明（"history"）。
  • 按需抓取： Pro 每 24 小时 20 次、Team 100 次（与网页端共用），每 30 秒最多一次。

响应与错误

所有响应使用统一信封，HTTP 状态码同步给出：

{ "code": 0, "message": "ok", "data": { "items": [], "total": 0 } }

出错时 code 为 -1，message 是机器可读的错误码：

HTTPmessage含义
400invalid_request、invalid_json、invalid_url参数错误
401missing_api_key、invalid_api_key未带密钥，或密钥已删除 / 无效
402insufficient_credits剩余积分不足
403plan_required当前套餐不含 API / MCP
404not_found广告、实体或抓取请求不存在
422rejected该站点已申请退出抓取
429rate_limited、daily_limit、too_many_requests请求过快 / 已达每日抓取上限
503not_ready、unavailable数据或抓取服务暂不可用

接口

方法与路径说明
GET /api/v1/ads搜索广告。筛选条件放在查询参数中，列表用逗号分隔。
POST /api/v1/ads/search同上，使用 JSON 请求体（列表为数组）。
GET /api/v1/ads/{id}单条广告：分布、时间线、主要媒体、落地页与跳转链。
GET /api/v1/advertisers/{id}广告主档案（?days=7,30,90,365）。
GET /api/v1/publishers/{domain}媒体（网站）档案。
GET /api/v1/networks/{id}广告网络档案。
GET /api/v1/coverage覆盖账本：网络 × 格式 × 国家，近 24 小时与 7 天。
POST /api/v1/crawl-requests提交抓取：{ "url", "geo", "device" }。
GET /api/v1/crawl-requests最近的抓取请求与今日用量。
GET /api/v1/crawl-requests/{id}单个抓取请求的状态。
GET /api/v1/me/usage套餐、限额、积分余额与本月用量。

搜索参数： q、adTypes、networks、geos、devices、platforms、advertiserIds、publisherIds（如 web:example.com）、landingDomains、languages、verticals、sizes（300x250）、seenFrom / seenTo、firstSeenFrom / firstSeenTo（新广告）、minDaysSeen、minPublishers、hasLandingPage、riskMin、sort（last_seen、first_seen、days_seen、publishers、impressions）、order、page、pageSize（最大 50）。

impressions 表示我们的爬虫观测到这条广告的次数，不是实际曝光量、花费或覆盖人数。

curl -X POST https://adsup.ai/api/v1/ads/search \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"adTypes":["native"],"geos":["US"],"firstSeenFrom":"2026-11-01","sort":"first_seen"}'

MCP 服务

MCP 服务地址为 https://adsup.ai/api/mcp（Streamable HTTP），与 REST API 使用相同的密钥、积分和限额。服务基于官方 MCP TypeScript SDK，无状态，任何符合规范的客户端都可连接。

工具：search_ads、get_ad、get_advertiser、get_publisher、get_network、coverage、request_crawl、get_crawl_request、get_usage。每次工具调用的积分与对应 REST 接口相同；握手和工具列表免费。

Claude Code：

claude mcp add --transport http adsup https://adsup.ai/api/mcp \
  --header "Authorization: Bearer sk_your_key"

使用 JSON 配置的客户端（如 Claude Desktop、Cursor）：

{
  "mcpServers": {
    "adsup": {
      "type": "http",
      "url": "https://adsup.ai/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_key" }
    }
  }
}

然后可以这样提问：“找出本周在德国首次出现的 VPN 类原生广告，并总结它们的落地页。”

告警 Webhook

Team 套餐可以把保存搜索的每日告警同时推送到 Webhook（在 保存的搜索与告警 中设置）。Slack Incoming Webhook 地址（hooks.slack.com）会收到 Slack 消息，其他地址收到：

{
  "type": "alert.new_ads",
  "alert_id": "…",
  "rule": { "kind": "saved_search", "target": "…", "name": "VPN native US" },
  "count": 3,
  "ads": [
    {
      "id": "…",
      "title": "…",
      "thumb_url": "…",
      "url": "https://adsup.ai/app/ads/…"
    }
  ],
  "sent_at": "2026-11-07T06:00:00.000Z"
}

请校验 X-Adsup-Signature: t=<unix>,v1=<hex> 头：v1 是用 Webhook 旁显示的签名密钥对 t + "." + body 计算的 HMAC-SHA256。Webhook 地址必须是公网主机上的 https://，不跟随重定向。