> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取采集器填充率

> 获取 Bright Data Scraper API 采集器的逐字段填充率。GET /datasets/v3/scraper/{id}/fill_rate 汇总账户在最长 31 天内采集的快照，返回每个字段的填充数、评估数和百分比。

此端点显示在最长 31 天的时间范围内，账户使用某个 Scraper API 采集器采集的快照中，每个输出字段有值的比例。

> [!TIP]
>
> 如需在购买前查看 Marketplace 数据集的填充率，请参阅 [数据集市场填充率](https://docs.brightdata.com/cn/products/marketplace/fill-rates-and-statistics.md)。


## OpenAPI

````yaml cn-dca-api get /datasets/v3/scraper/{dataset_id}/fill_rate
openapi: 3.1.0
info:
  title: Brightdata API
  description: 用于与数据集市场交互的 API
  version: 1.0.0
servers:
  - url: https://api.brightdata.com
security:
  - bearerAuth: []
paths:
  /datasets/v3/scraper/{dataset_id}/fill_rate:
    get:
      description: >-
        返回某个采集器在 `from_date` 与 `to_date`
        之间由账户采集的所有快照中汇总的字段填充率。对于每个输出字段，响应会给出已填充值的评估记录数（`filled`）、评估记录总数（`total`）以及百分比（`fill_rate`）。


        - 时间范围最长为 31 天。超出范围将返回 HTTP 400 `Max date range is 31 days`。

        - 没有匹配的快照时，请求仍返回 HTTP 200，`snapshots_count` 为 `0`，`fields` 为空数组。账户从未使用过的
        `dataset_id` 也是如此。
      operationId: getScraperFillRate
      parameters:
        - name: dataset_id
          in: path
          required: true
          description: >-
            采集器的数据集 ID，例如 `gd_l7q7dkf244hwjntr0`（Amazon
            商品）。可通过[获取所有采集器](/cn/api-reference/scrapers/management-apis/get-scrapers)查找数据集
            ID。
          schema:
            type: string
            example: gd_l7q7dkf244hwjntr0
        - name: from_date
          in: query
          required: true
          description: 时间范围的开始，ISO 8601 格式。不带时间的日期（`2026-11-01`）按 UTC 零点处理。
          schema:
            type: string
            format: date-time
            example: '2026-11-01T00:00:00.000Z'
        - name: to_date
          in: query
          required: true
          description: 时间范围的结束，ISO 8601 格式。必须不早于 `from_date`，且与其相差不超过 31 天。
          schema:
            type: string
            format: date-time
            example: '2026-11-16T00:00:00.000Z'
      responses:
        '200':
          description: 所请求采集器和时间范围的填充率
          content:
            application/json:
              schema:
                type: object
                properties:
                  dataset_id:
                    type: string
                    description: 采集器的数据集 ID。
                  from_date:
                    type: string
                    description: 所请求时间范围的开始，规范化为带毫秒的 ISO 8601 格式。
                    format: date-time
                  to_date:
                    type: string
                    description: 所请求时间范围的结束，规范化为带毫秒的 ISO 8601 格式。
                    format: date-time
                  snapshots_count:
                    type: integer
                    description: 账户在该时间范围内使用此采集器采集的快照数量。
                  included_snapshots_count:
                    type: integer
                    description: >-
                      参与填充率计算的快照数量。当部分快照没有填充率统计时会低于
                      `snapshots_count`：包括未采集到任何成功记录的快照，以及未记录字段统计的较早快照。对这些快照调用[获取快照填充率](/cn/api-reference/scrapers/management-apis/get-snapshot-fill-rates)会返回
                      HTTP 409。
                  fields:
                    type: array
                    description: 每个输出字段一项。没有快照参与计算时为空。
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: 输出字段的名称。
                        filled:
                          type: integer
                          description: 该字段有填充值的评估记录数。
                        total:
                          type: integer
                          description: 在参与计算的快照中，该字段被评估的记录总数。不同字段的值可能不同。
                        fill_rate:
                          type: number
                          description: >-
                            有填充值的评估记录所占百分比，范围 `0` 到 `100`，保留两位小数：`filled / total
                            * 100`。
              examples:
                fill_rates:
                  summary: Amazon 商品，15 天（部分字段）
                  value:
                    dataset_id: gd_l7q7dkf244hwjntr0
                    from_date: '2026-11-01T00:00:00.000Z'
                    to_date: '2026-11-16T00:00:00.000Z'
                    snapshots_count: 207
                    included_snapshots_count: 207
                    fields:
                      - name: title
                        filled: 299
                        total: 299
                        fill_rate: 100
                      - name: final_price
                        filled: 253
                        total: 299
                        fill_rate: 84.62
                      - name: seller_name
                        filled: 240
                        total: 285
                        fill_rate: 84.21
                      - name: categories
                        filled: 92
                        total: 285
                        fill_rate: 32.28
                no_snapshots:
                  summary: 时间范围内没有快照
                  value:
                    dataset_id: gd_l7q7dkf244hwjntr0
                    from_date: '2026-12-01T00:00:00.000Z'
                    to_date: '2026-12-05T00:00:00.000Z'
                    snapshots_count: 0
                    included_snapshots_count: 0
                    fields: []
        '400':
          description: |-
            查询参数无效

            消息：
            - `"from_date" is required` / `"to_date" is required`
            - `"from_date" must be in ISO 8601 date format`
            - `"to_date" must be greater than or equal to "ref:from_date"`
            - `Max date range is 31 days`（纯文本响应体）
          content:
            application/json:
              schema:
                type: object
                properties:
                  validation_errors:
                    type: array
                    items:
                      type: string
              examples:
                missing_dates:
                  value:
                    validation_errors:
                      - '"from_date" is required'
                      - '"to_date" is required'
            text/plain:
              schema:
                type: string
              examples:
                range_too_long:
                  value: Max date range is 31 days
        '401':
          description: |-
            缺少 API 密钥或 API 密钥无效

            消息（纯文本响应体）：
            - `Credentials are missing`
            - `Invalid credentials`
          content:
            text/plain:
              schema:
                type: string
              examples:
                invalid_key:
                  value: Invalid credentials
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。


        **认证方法:**

        1. 从 Bright Data 账户设置获取您的 API Key:
        https://brightdata.com/cp/setting/users

        2. 在请求的 Authorization 头中包含 API Key

        3. 格式: `Authorization: Bearer YOUR_API_KEY`


        **示例:**

        ```

        Authorization: Bearer
        b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

        ```


        了解如何获取 Bright Data API Key:
        https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key？
      bearerFormat: API Key

````