如何对 Business Search 结果分页

本指南通过用递增的 offset 重复同一次搜索，直到某一页返回不足一页或为空为止，采集与一个 Business Search 查询匹配的全部记录。

前提条件

一个已开通 Business Search 权限的 Bright Data API key，并已按快速开始的第 1 步存入环境变量 BRIGHTDATA_API_KEY
一个第一页就已返回目标记录的查询。请先用 Business Search 查询语法调好条件，再进行分页

第 1 步：发送第一页

发送搜索请求，offset 设为 0，limit 设为页大小。limit 默认为 10，其上限取决于模式：

模式	单页 `limit` 上限
`ludicrous`	100
`instant`	100
`smart`	10

一次搜索最多能翻多远同样取决于模式：

Ludicrous 接受最大 1,000 的 offset，因此一次搜索最多可以翻阅 1,100 条记录。
Instant 和 Smart 只开放一次搜索的前 100 条匹配。offset 加 limit 不能超过 100，因此请在该窗口内分页，或把相同条件写成结构化查询在 Ludicrous 模式下运行。

下面的请求获取一次 Ludicrous 公司搜索的前 100 条匹配。高亮行设置分页：

curl --request POST "https://api.brightdata.com/search/company" \
  --header "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source": "linkedin_company",
    "mode": "ludicrous",
    "query": {
      "and": [
        { "text": { "industry": "software" } },
        { "equals": { "headquarters_country_code": "US" } },
        { "range": { "employees_in_linkedin": { ">=": 50, "<=": 500 } } }
      ]
    },
    "offset": 0,
    "limit": 100,
    "view": "summary"
  }'

import os
import requests

response = requests.post(
    "https://api.brightdata.com/search/company",
    headers={
        "Authorization": f"Bearer {os.environ['BRIGHTDATA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "source": "linkedin_company",
        "mode": "ludicrous",
        "query": {
            "and": [
                {"text": {"industry": "software"}},
                {"equals": {"headquarters_country_code": "US"}},
                {"range": {"employees_in_linkedin": {">=": 50, "<=": 500}}},
            ]
        },
        "offset": 0,
        "limit": 100,
        "view": "summary",
    },
)

print(response.text)

const response = await fetch("https://api.brightdata.com/search/company", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRIGHTDATA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: "linkedin_company",
    mode: "ludicrous",
    query: {
      and: [
        { text: { industry: "software" } },
        { equals: { headquarters_country_code: "US" } },
        { range: { employees_in_linkedin: { ">=": 50, "<=": 500 } } },
      ],
    },
    offset: 0,
    limit: 100,
    view: "summary",
  }),
});

console.log(await response.text());

响应会在 meta.offset 和 meta.limit 中回显分页参数，并在 documents 中返回本页记录。完整的 meta 结构参见搜索公司 API 参考。

第 2 步：请求下一页

把 limit 加到 offset 上，然后原样再次发送请求体，其他属性保持不变。类目、数据源、模式、查询和视图都必须相同，因为改动其中任何一项都等于开始一次不同的搜索。第一页返回满页之后，下面的请求获取同一次搜索的第 101 到 200 条记录。只有高亮的 offset 发生变化：

curl --request POST "https://api.brightdata.com/search/company" \
  --header "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source": "linkedin_company",
    "mode": "ludicrous",
    "query": {
      "and": [
        { "text": { "industry": "software" } },
        { "equals": { "headquarters_country_code": "US" } },
        { "range": { "employees_in_linkedin": { ">=": 50, "<=": 500 } } }
      ]
    },
    "offset": 100,
    "limit": 100,
    "view": "summary"
  }'

import os
import requests

response = requests.post(
    "https://api.brightdata.com/search/company",
    headers={
        "Authorization": f"Bearer {os.environ['BRIGHTDATA_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "source": "linkedin_company",
        "mode": "ludicrous",
        "query": {
            "and": [
                {"text": {"industry": "software"}},
                {"equals": {"headquarters_country_code": "US"}},
                {"range": {"employees_in_linkedin": {">=": 50, "<=": 500}}},
            ]
        },
        "offset": 100,
        "limit": 100,
        "view": "summary",
    },
)

print(response.text)

const response = await fetch("https://api.brightdata.com/search/company", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BRIGHTDATA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: "linkedin_company",
    mode: "ludicrous",
    query: {
      and: [
        { text: { industry: "software" } },
        { equals: { headquarters_country_code: "US" } },
        { range: { employees_in_linkedin: { ">=": 50, "<=": 500 } } },
      ],
    },
    offset: 100,
    limit: 100,
    view: "summary",
  }),
});

console.log(await response.text());

重复本步骤，直到满足第 3 步的停止条件。

不要用 meta.matched 来驱动循环。meta.matched 是本次搜索触及的匹配数的下界而非总数，并且会在不同请求之间变化。越出模式窗口也不会返回空页：在 Instant 和 Smart 模式下，offset 加 limit 超过 100 的请求会返回 HTTP 500 和 error_code backend_search_failed；在 Ludicrous 模式下，offset 超出支持的上限会返回 HTTP 400 和 error_code invalid_query。

第 3 步：遇到不足一页或空页时停止

当 documents 返回为空或短于 limit 时停止。这一页就是结果集的最后一页。 Ludicrous 请求越过最后一条匹配后会返回 HTTP 200 和空的 documents 数组，因此空页是搜索的正常终点，而不是错误。如果 Instant 或 Smart 请求在前几页成功之后返回 HTTP 500 和 error_code backend_search_failed，说明循环已越出这两种模式的 100 条记录窗口。各状态码的其他原因参见 Business Search 错误代码。第一页的 documents 数组为空表示本次搜索没有匹配结果，并不能证明不存在这样的公司或人物。

第 4 步：对采集到的记录去重

每一页都是对当前索引的一次新搜索，而不是固定快照的一个切片，因此在分页过程中记录可能在页之间移动。请在一次运行中采集完所有页面，并按 bright_id 加 source 去重。不要在之后单独重新获取某一页并期望得到相同的记录。

常见问题

可以把 meta.matched 当作结果数量吗

不可以。meta.matched 表示本次搜索触及的匹配数量，请把它当作下界而非完整计数，对文本搜索和自然语言搜索尤其如此，并且它会随 offset 增大而增长。不要用它来估算数据集规模，也不要据此告诉用户恰好有这么多公司或人物符合他们的意图。

如何从 Instant 或 Smart 搜索中采集超过 100 条记录

把相同条件写成结构化查询，在 Ludicrous 模式下运行。Instant 和 Smart 只开放一次搜索的前 100 条匹配，而 Ludicrous 最多可翻到 offset 1,000。结构化查询的运算符和可搜索字段参见 Business Search 查询语法。

meta.coverage_percent 对分页结果集意味着什么

meta.coverage_percent 表示索引中作出响应的比例。低于 100 表示结果集不完整，基于该响应生成的结果页面应如实说明。等于 100 也不代表已返回全部相关记录或所有字段都有值。

为什么相同的 offset 返回了不同的记录

每一页都是一次新搜索，而且索引每日刷新，因此结果及其顺序可能在不同请求之间发生变化。某次运行中位于第 1 页的记录，在下一次运行中可能出现在第 2 页。如果任务需要稳定的结果集，请按第 4 步在一次运行中采集完所有页面并去重。

开始使用

数据提取

网页搜索

AI 训练数据

代理网络

如何对 Business Search 结果分页

前提条件

第 1 步：发送第一页

第 2 步：请求下一页

第 3 步：遇到不足一页或空页时停止

第 4 步：对采集到的记录去重

常见问题

可以把 meta.matched 当作结果数量吗

如何从 Instant 或 Smart 搜索中采集超过 100 条记录

meta.coverage_percent 对分页结果集意味着什么

为什么相同的 offset 返回了不同的记录

​前提条件

​第 1 步：发送第一页

​第 2 步：请求下一页

​第 3 步：遇到不足一页或空页时停止

​第 4 步：对采集到的记录去重

​常见问题

​可以把 meta.matched 当作结果数量吗

​如何从 Instant 或 Smart 搜索中采集超过 100 条记录

​meta.coverage_percent 对分页结果集意味着什么

​为什么相同的 offset 返回了不同的记录

前提条件

第 1 步：发送第一页

第 2 步：请求下一页

第 3 步：遇到不足一页或空页时停止

第 4 步：对采集到的记录去重

常见问题

可以把 meta.matched 当作结果数量吗

如何从 Instant 或 Smart 搜索中采集超过 100 条记录

meta.coverage_percent 对分页结果集意味着什么

为什么相同的 offset 返回了不同的记录