跟踪 AI 搜索引擎

使用 /batches 加上 GEO/AEO（生成引擎优化/答案引擎优化）解析器来大规模查询 AI 搜索引擎，并获取结构化的 JSON：答案、引用以及广告、购物卡和产品模块等商业界面。本页介绍如何调用 /v1/batches 以及你收到的 JSON 的简要预览。

引擎

每个引擎需要其自己的解析器 ID 和 URL 模板。在批处理级别传递解析器一次。将查询编码在 URL 中。

引擎	解析器	URL 模板	积分	最大项目数
Google AI Mode	`@olostep/google-aimode-results`	`https://www.google.com/aimode?q={query}`	3	2500
Google AI Overview	`@olostep/google-ai-overview-results`	`https://www.google.com/search?q={query}`	3	2500
ChatGPT	`@olostep/chatgpt-results`	`https://chatgpt.com/?q={query}`	5	2500
Perplexity	`@olostep/perplexity-results`	`https://www.perplexity.ai/?q={query}`	3	2500
Gemini	`@olostep/gemini-results`	`https://gemini.google.com/?q={query}`	3	2500
Microsoft Copilot	`@olostep/microsoft-copilot-results`	`https://copilot.microsoft.com/chats?q={query}`	3	1000

所有六个引擎都支持通过批处理 country 参数（ISO 3166-1 alpha-2）进行地理定位。国家覆盖范围因解析器而异——获取实时列表而不是硬编码：

curl "https://api.olostep.com/v1/countries?service=batches&parser=@olostep/google-aimode-results"

当你关注引用时，使用信息提示（what is mitochondria）。当你需要广告、购物卡或产品模块时，使用商业提示（best wireless headphones under $200）——这些界面是基于意图检测的，当引擎不呈现它们时会被省略。

1. 创建批处理

custom_id 在批处理中必须唯一。country 应用于每个项目。

from olostep import Olostep
from urllib.parse import quote_plus

client = Olostep(api_key="YOUR_API_KEY")

queries = [
    "what is mitochondria",
    "best wireless headphones under $200",
]

batch = client.batches.create(
    urls=[
        {
            "custom_id": f"aimode-{i}",
            "url": f"https://www.google.com/aimode?q={quote_plus(q)}",
        }
        for i, q in enumerate(queries, start=1)
    ],
    parser="@olostep/google-aimode-results",
    country="US",
)

print(batch.id, batch.status)

import Olostep from 'olostep'

const client = new Olostep({ apiKey: 'YOUR_API_KEY' })

const queries = [
  'what is mitochondria',
  'best wireless headphones under $200',
]

const batch = await client.batches.create(
  queries.map((q, i) => ({
    customId: `aimode-${i + 1}`,
    url: `https://www.google.com/aimode?q=${encodeURIComponent(q)}`,
  })),
  {
    parser: '@olostep/google-aimode-results',
    country: 'US',
  }
)

console.log(batch.id, batch.status)

curl -X POST "https://api.olostep.com/v1/batches" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parser": { "id": "@olostep/google-aimode-results" },
    "country": "US",
    "items": [
      {
        "custom_id": "aimode-1",
        "url": "https://www.google.com/aimode?q=what%20is%20mitochondria"
      },
      {
        "custom_id": "aimode-2",
        "url": "https://www.google.com/aimode?q=best%20wireless%20headphones%20under%20%24200"
      }
    ]
  }'

要针对不同的引擎，保持相同的 items 结构并交换 parser.id 和每个 URL 中的主机。一个批处理 = 一个解析器。

处理时间大致恒定，无论批处理大小（通常为 5–8 分钟）。在创建时传递 webhook 以获取 batch.completed 而不是轮询。新账户限制为每批 100 个项目——联系 info@olostep.com 以提高限制。

2. 等待完成

轮询 GET /v1/batches/{batch_id} 直到 status 为 completed，或处理 webhook。

import time
import requests

headers = {"Authorization": f"Bearer {API_KEY}"}

def wait_for_batch(batch_id):
    while True:
        info = requests.get(
            f"https://api.olostep.com/v1/batches/{batch_id}",
            headers=headers,
        ).json()
        if info["status"] == "completed":
            return info
        time.sleep(15)

async function waitForBatch(batchId) {
  while (true) {
    const res = await fetch(`https://api.olostep.com/v1/batches/${batchId}`, {
      headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` },
    })
    const info = await res.json()
    if (info.status === 'completed') return info
    await new Promise((r) => setTimeout(r, 15000))
  }
}

curl "https://api.olostep.com/v1/batches/batch_abc123" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY"

Python 和 Node SDK 可以为你等待：迭代 batch.items() / for await (const item of batch.items())，它们会阻塞直到批处理完成。

3. 检索 `json_content`

列出项目，然后为每个 retrieve_id 检索 JSON。GEO 负载是 json_content 内解析的对象（一个 JSON 字符串——解析它）。

import json
import requests

headers = {"Authorization": f"Bearer {API_KEY}"}

items = requests.get(
    f"https://api.olostep.com/v1/batches/{batch_id}/items",
    headers=headers,
).json()["items"]

for item in items:
    payload = requests.get(
        "https://api.olostep.com/v1/retrieve",
        headers=headers,
        params={"retrieve_id": item["retrieve_id"], "formats": "json"},
    ).json()
    data = json.loads(payload["json_content"])
    print(item["custom_id"], data.get("prompt"), len(data.get("sources") or []))

const itemsRes = await fetch(
  `https://api.olostep.com/v1/batches/${batchId}/items`,
  { headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` } }
)
const { items } = await itemsRes.json()

for (const item of items) {
  const params = new URLSearchParams({
    retrieve_id: item.retrieve_id,
    formats: 'json',
  })
  const payload = await fetch(
    `https://api.olostep.com/v1/retrieve?${params}`,
    { headers: { Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}` } }
  ).then((r) => r.json())

  const data = JSON.parse(payload.json_content)
  console.log(item.custom_id, data.prompt, (data.sources || []).length)
}

for item in batch.items():
    content = item.retrieve(["json"])
    print(item.custom_id, content.json_content)

失败的项目会单独列出——在 GET /v1/batches/{batch_id}/items 上传递 status=failed。托管的 JSON 也可以在检索负载的 json_hosted_url 上获得，大约 7 天。

你收到的内容

每个解析器返回 answer_markdown。大多数还返回 prompt。其余的是引擎特定的。下面的简要预览来自实时 country=US 批处理。

这里列出的引擎是公共 GEO 解析器。我们还在内部支持其他解析器和连接器，以及特定站点的自定义解析器——我们会根据请求分享这些。发送电子邮件至 info@olostep.com 或在 Slack 上联系我们。

引用在 sources 中（当内联引用时 cited: true）。结构化部分在 text_blocks 中（text、heading、list、table）。当 Google 显示赞助卡时，它们会在 ads 中——一个实时耳机查询返回了来源和比较表，但省略了 ads。空字段被剥离，不会作为 [] 返回。

{
  "answer_markdown": "When looking for the best wireless over-ear or on-ear headphones under $200...",
  "sources": [
    {
      "url": "https://www.reddit.com/r/HeadphoneAdvice/comments/173hvu2/best_wireless_headphones_for_under_200_dollars/",
      "title": "Best wireless headphones for under 200 dollars : r/HeadphoneAdvice",
      "description": "According to a Reddit user, the Sennheiser Accentum headphones are a good option...",
      "domain": "https://www.reddit.com",
      "cited": false
    }
  ],
  "text_blocks": [
    { "type": "text", "snippet": "When looking for the best wireless over-ear or on-ear headphones under $200..." },
    {
      "type": "table",
      "snippet": "Model | Best For | Key Features | Price Range",
      "data": {
        "headers": ["Model", "Best For", "Key Features", "Price Range"],
        "rows": [
          ["Anker Soundcore Space Q45", "Overall Value & ANC", "Strong adaptive ANC, 50-hour battery life", "~$100 - $150"]
        ]
      }
    }
  ]
}

内联芯片是 inline_references。来源抽屉是 sources。购物是 products。赞助品牌块是 ads（brand + cards）。空模块是 []。network_search_calls 是网络搜索跟踪。

{
  "url": "https://chatgpt.com/?q=best%20wireless%20headphones%20under%20%24200",
  "prompt": "best wireless headphones under $200",
  "answer_markdown": "If you mean **over-ear wireless headphones with ANC**...",
  "inline_references": [
    {
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "text": "The 5 Best Headphones Under $200 of 2026 - RTINGS.com",
      "position": 1
    }
  ],
  "sources": [
    {
      "url": "https://www.tomsguide.com/us/best-headphones-deals,news-28645.html",
      "title": "Best headphone deals for August 2026",
      "snippet": "This August 2026 headphone deal roundup...",
      "cited": false,
      "date_published": "2026-08-19T16:18:38.000Z",
      "attribution": "www.tomsguide.com"
    }
  ],
  "ads": [
    {
      "brand": { "name": "Razer", "url": "https://www.razer.com/" },
      "cards": [
        {
          "title": "Razer BlackShark V3 Pro",
          "body": "Pros swear by its unrivaled clarity...",
          "url": "https://www.razer.com/gaming-headsets/razer-blackshark-v3-pro?utm_source=chatgpt&...",
          "image": "https://bzrcdn.openai.com/fe8bef58c7129858.jpg"
        }
      ]
    }
  ],
  "products": [
    {
      "title": "Soundcore Space Q45",
      "price": 139.99,
      "currency": "$",
      "vendors": [
        {
          "price": 139.99,
          "currency": "$",
          "website": "Best Buy",
          "link": "https://www.bestbuy.com/product/soundcore-by-anker-space-q45-...?utm_source=chatgpt.com"
        }
      ]
    }
  ],
  "locations": [],
  "web_searched": true,
  "network_search_calls": {
    "search_triggered": true,
    "model_slug": "auto",
    "search_queries": [
      { "query": "best wireless headphones under $200 2026 Sony WH-CH720N Soundcore Space Q45...", "type": "model_query" }
    ]
  }
}

shopping_cards、videos、images、hotels 和 places 是未显示模块时的空数组。search_model_queries 是 Perplexity 实际搜索的内容。

{
  "url": "https://www.perplexity.ai/search/53051455-01ac-48a2-8aa7-45e518588af0",
  "prompt": "best wireless headphones under $200",
  "answer_markdown": "*   Anker Soundcore Space Q45 Wireless...",
  "sources": [
    {
      "position": 1,
      "label": "The 5 Best Headphones Under $200 of 2026",
      "url": "https://www.rtings.com/headphones/reviews/best/by-price/under-200",
      "description": "",
      "domain": "www.rtings.com",
      "date": ""
    }
  ],
  "related_queries": [
    "best budget wireless headphones under 200 dollars for sound quality"
  ],
  "shopping_cards": [],
  "videos": [],
  "images": [],
  "hotels": [],
  "places": [],
  "search_model_queries": [
    { "query": "best wireless headphones under $200", "engine": "web", "limit": 8 }
  ],
  "model": "perplexity",
  "web_searched": true
}

text_blocks 是分段和列表的概述。sources 是 AIO 引用。organic_results 是下面的经典 SERP（如果存在）。

{
  "url": "https://www.google.com/search?q=what+is+mitochondria&gl=us",
  "prompt": "what is mitochondria",
  "answer_markdown": "mitochondria\n\nMitochondria are membrane-bound organelles...",
  "sources": [
    {
      "title": "The Mitochondria",
      "url": "https://www.youtube.com/watch?v=sl6RXHnAMVs&t=7",
      "source": "YouTube",
      "index": 1
    }
  ],
  "text_blocks": [
    { "type": "paragraph", "snippet": "mitochondria\n\nMitochondria are membrane-bound organelles..." }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "Mitochondria",
      "link": "https://www.genome.gov/genetics-glossary/Mitochondria",
      "snippet": "Mitochondria are membrane-bound cell organelles..."
    }
  ]
}

{
  "url": "https://gemini.google.com/app/d11cddf049763b9b",
  "prompt": "best wireless headphones under $200",
  "answer_markdown": "Finding great wireless headphones under $200...",
  "sources": [
    {
      "position": 1,
      "label": "Best Noise Cancelling Headphones under $200 (50+ Tested!)",
      "url": "https://recordingnow.com/blog/best-budget-wireless-headphones/",
      "description": "The Sony WH-CH720N is the LIGHTEST full-sized...",
      "confidence_level": 9
    }
  ],
  "links_attached": true,
  "model": "gemini"
}

sources[].position 是 answer_markdown 中的字符偏移量，而不是排名。cited 表示来源是否在答案中附加。

{
  "url": "https://copilot.microsoft.com/chats?q=best%20wireless%20headphones%20under%20%24200",
  "prompt": "best wireless headphones under $200",
  "answer_markdown": "**The best wireless headphones under $200 in 2026 are the Sony WH-CH720N...",
  "sources": [
    {
      "url": "https://progressiveradionetwork.com/best-wireless-headphones-under-200-dollars/",
      "title": "10 Best Wireless Headphones Under 200$ (August 2026) Tested",
      "position": 1124,
      "icon_url": "https://services.bingapis.com/favicon?url=progressiveradionetwork.com",
      "cited": true
    }
  ]
}

示例

引擎

1. 创建批处理

2. 等待完成

3. 检索 `json_content`

你收到的内容

相关

​引擎

​1. 创建批处理

​2. 等待完成

​3. 检索 json_content

​你收到的内容

​相关

引擎

1. 创建批处理

2. 等待完成

3. 检索 `json_content`

你收到的内容

相关