GEOly Agent API

GEOly Agent API 就是 geoly run 背后的 HTTP 接口。你发一个问题，GEOly 托管的 GEO Agent 自己挑选数据工具，读取你的监测数据（套餐包含时也会用到公开行业数据），返回答案和一张回执：用了哪些工具、走了几步、花了多少。你不需要写提示词，也不需要了解 GEOly 的数据结构——拿到的就是答案。

GEOly CLI 是这个接口的官方客户端：用它登录后，geoly run 会发送请求、跟随事件流、安全重试并保存回执。本页说明其下的 HTTP 接口——端点、请求与响应结构、流式、幂等和错误码——让你清楚一次运行会返回什么。

与 CLI、MCP 的关系

三者使用同一套 GEOly OAuth 授权、同样的组织与品牌、同样的权限。

快速开始

GEOly CLI 就是这个接口的官方客户端：geoly run 会替你登录、发送下文的请求、跟随事件流、安全重试并保存回执。

# 1. 安装 CLI 并登录一次
curl -fsSL https://geoly.ai/install.sh | sh
geoly auth login

# 2. 提问——背后就是一次 POST /api/agent/runs
geoly run "过去 7 天我们在 ChatGPT 上的可见度怎么变的？"

Agent 工作时 stderr 上会显示它的步骤和工具，结束后 stdout 输出一张 JSON 回执。本页其余部分说明 HTTP 接口本身：geoly run 发出什么、收到什么。

鉴权

用 GEOly CLI 登录：

geoly auth login                  # 打开浏览器登录
geoly auth login --remote         # 本机没有浏览器：打印一个可在任意设备打开的链接……
geoly auth login --code <code>    # ……再把页面上显示的授权码贴回来

授权同意页会让你选择组织、确认读取权限（需要时再勾选写入）——与 GEOly MCP 是同一个页面。登录会为你的 GEOly 账号签发一个 OAuth 访问令牌，有效期约 14 天；geoly auth status 可查看到期时间，重新登录即可续期。SSH、容器和 CI Runner 上的完整登录流程见 GEOly CLI 文档。

在协议层面，每个请求都带着这个令牌：

Authorization: Bearer <access_token>

不接受浏览器登录态的 Cookie。令牌代表你的 GEOly 用户以及你当时的授权：接口能访问的组织和权限与这份授权完全一致，不会更多。令牌缺失、无效或过期时返回 401。

接口一览

基础地址：https://app.geoly.ai

发起一次运行

POST /api/agent/runs
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: text/event-stream
Idempotency-Key: weekly-report-2026-09-22

{
  "question": "对比过去 30 天我们和前三名竞品的 AI 可见度。",
  "org_id": "<org_id>",
  "brand_id": "<brand_id>",
  "context": "我们在美国卖升降桌。答案控制在 300 字以内。",
  "max_credits": 300
}

需要 org_id 或 brand_id 却没传（或传错）时，400 报错会按名称列出可选项，例如 This organization has multiple brands. Pass brand_id explicitly …，或 brand_id "…" was not found in this organization. Did you mean …? Available: …。

流式（Server-Sent Events，推荐）

请求头带 Accept: text/event-stream，响应是如下格式的事件流：

event: started
data: {"run_id":"run_…","brand":{"id":"…","name":"…"},"model":"…"}

event: tool
data: {"name":"get_brand_overview","ok":true,"ms":1830,"args":{"time_range":"30d"},"output_chars":5120}

event: done
data: {"run_id":"run_…","answer":"…","stopped":"done", …}

流式模式下运行失败以 error 事件给出，HTTP 状态码仍是 200。

客户端断开后运行会继续跑完，结果照常保存。断开的流无法续接，但随时可以用 GET /api/agent/runs/{run_id} 取回结果。

JSON（同步）

不带 Accept: text/event-stream，运行结束后一次性返回 JSON 回执。只适合简单问题：这种模式下约 30 秒后 Agent 不再开始新的步骤，而且响应超过约 100 秒可能被网络边缘以网关错误中断。即便如此，运行仍会完成并保存，可以用 GET /api/agent/runs 找到它，再按 id 读取。运行失败时返回 502 和 {"error":"RUN_FAILED","message":"…"}。

回执

流式模式下的 done 事件，或 JSON 模式的响应体：

{
  "run_id": "run_…",
  "answer": "…Markdown…",
  "stopped": "done",
  "stopped_reason": "done",
  "steps": 3,
  "tools_used": ["get_brand_overview", "get_brand_board"],
  "usage": { "input_tokens": 46253, "output_tokens": 1489 },
  "credits_cost": 54,
  "credits_remaining": 9946
}

取回运行记录

GET /api/agent/runs?org_id=<org_id>&limit=20
GET /api/agent/runs/{run_id}

GET /api/agent/runs 返回 { "runs": [ … ] }，按时间倒序。每行包含 run_id、status、stopped、steps、credits_cost、created_at、finished_at、question（前 200 字符）和 brand_id。limit 为 1–50（默认 20）；可访问多个组织时请传 org_id。

GET /api/agent/runs/{run_id} 返回保存的运行记录：

{
  "run_id": "run_…",
  "status": "succeeded",
  "question": "…",
  "answer": "…",
  "stopped": "done",
  "steps": 3,
  "tools_used": ["…"],
  "usage": { "input_tokens": 46253, "output_tokens": 1489 },
  "credits_cost": 54,
  "max_credits": 2000,
  "error": null,
  "created_at": "2026-09-22T08:00:00.000Z",
  "finished_at": "2026-09-22T08:01:12.000Z"
}

• 这里的 status 取值为 running、succeeded 或 failed（CLI 会把 succeeded 显示为 done）。
• 想等待运行结束，每隔几秒轮询一次这个接口，直到 status 不再是 running。
• 开始 15 分钟后仍标记为 running 的运行，会按 failed、error: "RUN_ABANDONED" 返回。
• 你的令牌无权查看的运行一律返回 404 RUN_NOT_FOUND，不论它是否存在。

幂等：安全重试

发送 Idempotency-Key 请求头即可安全重试：

• 格式：8–128 位，字符限 A-Z a-z 0-9 _ - : .。带了这个头但格式不对（包括空值）会返回 400 IDEMPOTENCY_KEY_INVALID。
• 作用范围：同一组织、同一品牌、同一个键。
• 原运行还在进行中时，同键请求一律返回那次运行。
• 原运行结束后，从它开始的时间算起 10 分钟内，同键请求都回放它；超过 10 分钟，同一个键会发起新的运行。
• 回放不会新开运行，也不会再扣费。无论 Accept 填什么，回放都以 JSON 返回，响应体里带 "replayed": true，响应头带 Idempotent-Replayed: true。响应体结构与 GET /api/agent/runs/{run_id} 相同；如果其中 status 是 running，轮询该接口即可。
• 如果暂时无法校验幂等键，请求会以 503 IDEMPOTENCY_UNAVAILABLE 拒绝，而不是冒着重复运行的风险放行。请用同一个键重试。

建议用能标识任务的键，例如 weekly-report-<品牌>-<日期>。CLI 的键由组织、品牌、spec、问题、context、max_credits 和写入意愿共同生成。

Credits

Agent API 的用量消耗你所在组织自己的 credits。

• 给运行封顶： 用 max_credits（25–2000）。回执中的 credits_cost 不会超过它。
• 查看剩余： 每张回执里都有 credits_remaining；也可以用 geoly credits，或在 GEOly 的 设置 → 账单 查看。
• 运行失败不收费。
• 组织剩余不足 25 credits 时，运行会以 402 INSUFFICIENT_CREDITS 被拒绝（响应体带 remaining，已知时还带 period_end）。

固定格式交付物（spec）

传入 spec 后，Agent 按服务端维护的规范交付：章节固定、每个数字都来自工具、末尾附一段机器可读的 JSON。回执中的 deliverable 字段给出是否通过校验。带 spec 的流式运行时限更长。

把这些信息直接写进 question，例如 "url: https://example.com/blog/x, query: best standing desk for small apartments, country: us"。名称不存在时返回 400 SPEC_NOT_FOUND: … Available: …。

错误码

错误以 JSON 返回：{ "error": "<错误码或说明>" }，部分错误带额外字段。

频率与并发

• 请求与 GEOly MCP 共用同一个按账号、按分钟计的频率限制，超限返回 429，请退避后再试。
• 没有单独的并发运行上限。每次运行开始时会按自身预算预留额度，所以同时发起多次运行时，每一次都会占用组织的 credits。

示例：Python

import json
import os

import requests

TOKEN = os.environ["GEOLY_ACCESS_TOKEN"]  # 你的 GEOly OAuth 访问令牌

resp = requests.post(
    "https://app.geoly.ai/api/agent/runs",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
        "Accept": "text/event-stream",
        "Idempotency-Key": "weekly-review-2026-09-22",
    },
    json={"question": "总结一下我们本周的 AI 可见度。", "max_credits": 300},
    stream=True,
    timeout=(10, 60),  # 连接超时、空闲读取超时（心跳每 10 秒一次）
)
resp.raise_for_status()

if resp.headers.get("Content-Type", "").startswith("application/json"):
    print(resp.json())  # 幂等回放了之前的运行
else:
    event = None
    for line in resp.iter_lines(decode_unicode=True):
        if line.startswith("event:"):
            event = line[len("event:"):].strip()
        elif line.startswith("data:") and event in ("done", "error"):
            payload = json.loads(line[len("data:"):])
            print(event, payload.get("stopped_reason"), payload.get("answer") or payload.get("message"))

示例：用 curl 走 JSON 模式

curl https://app.geoly.ai/api/agent/runs \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"question":"这个月我们在 Perplexity 上的提及率是多少？","max_credits":100}'

接入建议

1. 优先用流式。 JSON 模式只用于确定几秒内就能答完的问题。
2. 把 heartbeat 当作正常事件，空闲超时设为 30 秒以上。
3. 记下 run_id。 断线和超时都不会丢答案，按 id 取回即可。
4. 先看 stopped_reason 再用答案。 自动化任务里，不是 done 时可以重跑或调高 max_credits。
5. 一次问清楚。 在 question 里写明时间范围、平台和输出形式，背景放进 context。
6. 可能重试的任务一律带 Idempotency-Key。

边界与限制

• 范围以授权为准。 接口只能访问令牌获得授权的组织与权限。
• 默认只读。 只有传 allow_writes: true，且在单组织授权中勾选了对应资源的写入权限，Agent 才会使用写入工具。按需触发监测（trigger_prompt）永远不对托管 Agent 开放。
• 套餐要求。 需要有效订阅；只有组织套餐包含公开行业情报时（Grow 及以上）才会用到它。
• 运行有上限。 单次运行最多 2,000 credits、20 步，并有时长限制（带 spec 时更长）。提前结束会在 stopped_reason 中说明。
• 模型固定。 接口使用 GEOly 选定的模型，不支持自带模型。
• 运行记录会保存，令牌所在组织范围内可以通过 GET /api/agent/runs 查看。

相关文档

• GEOly CLI——在终端或编码 Agent 里调用本接口最简单的方式。
• GEOly MCP 使用指南——在你自己的 AI 客户端里调用 GEOly 数据工具。