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

# Fill Rate Report

export const EndpointBadge = ({method = "GET", children}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-[#2AB673]"
    },
    POST: {
      bg: "mint-bg-[#3064E3]"
    },
    PUT: {
      bg: "mint-bg-[#C28C30]"
    },
    PATCH: {
      bg: "mint-bg-[#DA622B]"
    },
    DELETE: {
      bg: "mint-bg-[#CB3A32]"
    },
    API: {
      bg: "mint-bg-black"
    }
  };
  const key = method.toUpperCase();
  const styles = METHOD_STYLES[key] ?? METHOD_STYLES.API;
  return <div className="relative mt-7">
      <span className={`absolute -top-2 -left-2 z-10 ${styles.bg} text-white px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide`}>
        {key}
      </span>
      {children}
    </div>;
};

## Introduction

The fill rate report measures the placement impressions that were successfully filled in comparison to the total number of delivered placements. Retailers can leverage this data to analyze areas in demand and their supply that are impacting the ability to maximize yield.

***

## Endpoints

The report generation uses an asynchronous endpoint that is used to receive the report creation request (using a POST request); then, using the report `id` generated, it's possible to check the report status and download the output results using the following GET endpoint requests.

<table>
  <thead>
    <tr>
      <th>
        <p>
          Verb
        </p>
      </th>

      <th>
        <p>
          Endpoint
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /reports/fillrate
          </code>
        </p>
      </td>

      <td>
        <p>
          Request a fill rate report creation
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /reports/unfilled-placements
          </code>
        </p>
      </td>

      <td>
        <p>
          Request an unfilled reasons report
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            GET
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /reports/\{reportId}/status
          </code>
        </p>
      </td>

      <td>
        <p>
          Get status of a specific report
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            GET
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /reports/\{reportId}/output
          </code>
        </p>
      </td>

      <td>
        <p>
          Download output of a specific report
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## Report Request Attributes

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            supplyAccountIds
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          list\\
        </p>
      </td>

      <td>
        <p>
          Supply Account IDs to pull results for
        </p>

        <p>
          Accepted values: array of strings/int64
        </p>

        <p>
          Writable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            dimensions
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          list\\
        </p>
      </td>

      <td>
        <p>
          An array of strings used to define which dimensions to see in the report
        </p>

        <p>
          Accepted values: refer to Metrics and Dimensions for the complete list of supported dimensions
        </p>

        <p>
          Writable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            metrics
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          list\\
        </p>
      </td>

      <td>
        <p>
          An array of strings used to define which metrics to see in the report
        </p>

        <p>
          Accepted values: refer to Metrics and Dimensions for the complete list of supported metrics
        </p>

        <p>
          Writable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            startDate
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          date
        </p>
      </td>

      <td>
        <p>
          Start date of the report (inclusive)
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-dd
          </code>

          with max interval of 100 days with

          <code>
            endDate
          </code>
        </p>

        <p>
          Writable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            endDate
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          date
        </p>
      </td>

      <td>
        <p>
          End date of the report (inclusive)
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-dd
          </code>

          with max interval of 100 days with

          <code>
            startDate
          </code>
        </p>

        <p>
          Writable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            timezone
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Time zone to consider in the metrics calculation,

          <code>
            startDate
          </code>

          and

          <code>
            endDate
          </code>
        </p>

        <p>
          Accepted values: <a href="https://www.iana.org/time-zones">IANA (TZ database)</a> time zones (example:

          <code>
            America/New\_York
          </code>

          ,

          <code>
            Europe/Paris
          </code>

          ,

          <code>
            Asia/Tokyo
          </code>

          ,

          <code>
            UTC
          </code>

          )
        </p>

        <p>
          Default:

          <code>
            UTC
          </code>
        </p>

        <p>
          Writable? N / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            format
          </code>
        </p>
      </td>

      <td>
        <p>
          enum
        </p>
      </td>

      <td>
        <p>
          The format type the report should return results
        </p>

        <p>
          Accepted values:

          <code>
            json
          </code>

          ,

          <code>
            json-compact
          </code>

          ,

          <code>
            json-newline
          </code>

          ,

          <code>
            csv
          </code>
        </p>

        <p>
          Default:

          <code>
            json
          </code>
        </p>

        <p>
          Writable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            adServerType
          </code>
        </p>
      </td>

      <td>
        <p>
          enum
        </p>
      </td>

      <td>
        <p>
          The ad server responsible for rending the ad on the retailer site.
        </p>

        <p>
          Accepted values:

          <code>
            all
          </code>

          ,

          <code>
            gam
          </code>

          ,

          <code>
            criteo
          </code>
        </p>
      </td>
    </tr>
  </tbody>
</table>

<Info>
  **Field Definitions**

  * **Writeable (Y/N)**: Indicates if the field can be modified in requests.
  * **Nullable (Y/N)**: Indicates if the field can accept null/empty values.
  * **Primary Key**: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g., `retailerId`, `campaignId`, `lineItemId`) and are usually required in the URL path.
</Info>

***

## Create a Fill Rate Report request

This endpoint receives requests to create Fill Rate Reports and returns a report `id` (to be used in the next steps) in case the request was successfully created ; otherwise, will expose errors details about the request issues

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/reports/fillrate
  ```
</EndpointBadge>

**Sample Request**

```bash expandable theme={null}
curl -X 'POST' \
  'https://api.criteo.com/{version}/retail-media/reports/fillrate' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'Authorization: Bearer Add_token' \
  -d '{
  "data": {
    "type": "string",
    "attributes": {
      "supplyAccountIds": [
        "8639134211138xxxx"
      ],
      "dimensions": [
          "date",
          "retailerId",
          "retailerName",
          "placementId",
          "placementName",
          "pageTypeName",
          "environment",
          "servedCategory",
          "retailerCategoryId",
          "retailerCategoryName",
          "adServerType"
      ],
      "metrics": [
          "pageViews",
          "availablePlacements",
          "unfilledPlacements",
          "fillRate",
          "placementImpressions",
          "productImpressions",
          "impressions",
          "placementClicks",
          "productClicks",
          "clicks",
          "placementImpressionsCTR",
          "productImpressionsCTR",
          "cpm",
          "cpc",
          "placementImpressionsRevenue",
          "productClicksRevenue",
          "revenue",
          "workingMedia",
          "netRevenue",
          "nonDeliverablePlacements",
          "deliverablePlacements",
          "placementsWithCandidates",
          "coveredPlacements",
          "coverageRate"
                ],
      "adServerType": "all",
      "format": "csv",
      "startDate": "2025-09-08",
      "endDate": "2025-09-09",
      "timezone": "America/New_York"
    }
  }
}'
```

**Sample Response**: Report request successfully created (response status 🟢 `200`)

```json theme={null}
{
  "data": {
    "attributes": {
      "status": "pending",
      "rowCount": 0,
      "fileSizeBytes": 0,
      "md5CheckSum": null,
      "createdAt": "2025-09-15T19:00:29.056Z",
      "expiresAt": null,
      "message": null,
      "id": "48dec08e-5f65-41cd-9d77-85f87cxxxxx"
    },
    "id": "48dec08e-5f65-41cd-9d77-85f87xxxxxxx",
    "type": "StatusResponse"
  },
  "warnings": [],
  "errors": []
}
```

***

## Retrieve Unfilled Reasons

```http theme={null}
https://api.criteo.com/{version}/retail-media/reports/unfilled-placements
```

**Sample Request**

<Info>
  **List of Unfilled Reasons**

  Check the full list of supported unfilled reasons [here](/retail-media/docs/metrics-and-dimensions-ssp#fill-rate-unfilled-reasons)
</Info>

```bash expandable theme={null}
curl -X 'POST' \
  'https://api.criteo.com/{version}/retail-media/reports/unfilled-placements' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'Authorization: Bearer Add Token' \
  -d '{
  "data": {
    "type": "string",
    "attributes": {
      "supplyAccountIds": [
        "8639134211138xxxx"
      ],
      "dimensions": [
        "adServerType", "date"
      ],
      "metrics": [
              "totalUnfilledPlacements",
              "unfilledNotEnoughDemand",
              "nonDeliverableUnmappedCategories",
              "nonDeliverablePagesWithUnknownProducts",
              "nonDeliverableBlockedOptOut",
              "nonDeliverableBlockedPageCategory",
              "nonDeliverableInsufficientOrganicResults",
              "nonDeliverableTestPlacement",
              "uncoveredSearchTermWithoutCategory",
              "uncoveredNoDemandBrandedKeywordConquestingEnabled",
              "uncoveredNoDemandBrandedKeywordConquestingDisabled",
              "uncoveredNoDemandUnbrandedInventory",
              "uncoveredFilteredOutDemand",
              "uncoveredBrokenPlacement",
              "uncoveredNotPainted",
              "availablePlacements",
              "fillRate",
              "placementImpressions",
              "productImpressions",
              "placementClicks",
              "productClicks",
              "clicks",
              "placementImpressionsCTR",
              "productImpressionsCTR",
              "cpm",
              "cpc",
              "placementImpressionsRevenue",
              "productClicksRevenue",
              "revenue",
              "nonDeliverablePlacements",
              "placementsWithCandidates",
              "coveredPlacements",
              "coverageRate"
      ],
      "format": "csv",
      "startDate": "2025-09-08",
      "endDate": "2025-09-09",
      "timezone": "America/New_York"
    }
  }
}'
```

**Sample Response**

```json theme={null}
{
  "data": {
    "attributes": {
      "status": "pending",
      "rowCount": 0,
      "fileSizeBytes": 0,
      "md5CheckSum": null,
      "createdAt": "2025-09-15T19:45:55.758Z",
      "expiresAt": null,
      "message": null,
      "id": "4dcd1f71-77f0-4bf2-b225-3e7a0dxxxxx"
    },
    "id": "4dcd1f71-77f0-4bf2-b225-3e7a0ddxxxxxx",
    "type": "StatusResponse"
  },
  "warnings": [],
  "errors": []
}
```

***

## Get status of specific report

This endpoint retrieves the status of a specific report creation.\
Status can be `pending`, `success`, `failure`, or `expired`.

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/reports/{reportId}/status
  ```
</EndpointBadge>

**Sample Request**

```bash theme={null}
curl -L 'https://api.criteo.com/{version}/retail-media/reports/5f148e12-fba3-432e-b0d5-fe316xxxxx/status' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
```

**Sample Response**

```json theme={null}
{
    "data": {
        "id": "5f148e12-fba3-432e-b0d5-fe316xxxxxx",
        "type": "StatusResponse",
        "attributes": {
            "id": "5f148e12-fba3-432e-b0d5-fe3164axxxxx",
            "status": "success",
            "message": "rows_count=33490",
            "rowCount": 33490,
            "fileSizeBytes": 6669897,
            "createdAt": "2025-02-14T14:59:20.000Z",
            "expiresAt": "2025-02-21T15:00:00.000Z",
            "md5CheckSum": "801993bc0fe04e2b3fcf767a1c867a04"
        }
    },
    "warnings": [],
    "errors": []
}
```

***

## Download output of specific report

Once the report creation is completed (`"status": "success"` in response above), the report output will be available to download in this endpoint.

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/reports/{reportId}/output
  ```
</EndpointBadge>

**Sample Request**

```bash theme={null}
curl -X GET "https://api.criteo.com/{version}/retail-media/reports/2e733b8c-9983-4237-aab9-17a4xxxxxx/output" \
-H "Authorization: Bearer <MY_ACCESS_TOKEN>"
```

**Sample Responses**

Fill Rate and Coverage Rate

```json expandable theme={null}
[
 {
    "date": "2025-09-08",
    "retailerId": 180,
    "retailerName": "RetailerExample",
    "placementId": 21930,
    "placementName": "viewCategory_M-Butterfly2",
    "pageTypeName": "category",
    "environment": "mobile",
    "servedCategory": "tires & auto > auto & truck accessories > solar power systems",
    "retailerCategoryId": 695922,
    "retailerCategoryName": "solar power systems",
    "adServerType": "Criteo",
    "pageViews": null,
    "availablePlacements": 6,
    "unfilledPlacements": 6,
    "fillRate": null,
    "placementImpressions": null,
    "productImpressions": null,
    "impressions": null,
    "placementClicks": null,
    "productClicks": null,
    "clicks": null,
    "placementImpressionsCTR": null,
    "productImpressionsCTR": null,
    "cpm": null,
    "cpc": null,
    "placementImpressionsRevenue": 0,
    "productClicksRevenue": 0,
    "revenue": null,
    "workingMedia": null,
    "netRevenue": null,
    "nonDeliverablePlacements": 6,
    "deliverablePlacements": 0,
    "placementsWithCandidates": 0,
    "coveredPlacements": 0,
    "coverageRate": null
  },
  {
    "date": "2025-09-08",
    "retailerId": 180,
    "retailerName": "RetailerExample",
    "placementId": 21930,
    "placementName": "viewCategory_M-Butterfly2",
    "pageTypeName": "category",
    "environment": "mobile",
    "servedCategory": "toys > electronics for kids",
    "retailerCategoryId": 673065,
    "retailerCategoryName": "electronics for kids",
    "adServerType": "Criteo",
    "pageViews": null,
    "availablePlacements": 179,
    "unfilledPlacements": 179,
    "fillRate": null,
    "placementImpressions": null,
    "productImpressions": null,
    "impressions": null,
    "placementClicks": null,
    "productClicks": null,
    "clicks": null,
    "placementImpressionsCTR": null,
    "productImpressionsCTR": null,
    "cpm": null,
    "cpc": null,
    "placementImpressionsRevenue": 0,
    "productClicksRevenue": 0,
    "revenue": null,
    "workingMedia": null,
    "netRevenue": null,
    "nonDeliverablePlacements": 136,
    "deliverablePlacements": 43,
    "placementsWithCandidates": 179,
    "coveredPlacements": 0,
    "coverageRate": 0
  }
]
```

**Unfilled Placements**

```json expandable theme={null}
[
  {
    "adServerType": "Criteo",
    "date": "2025-09-30",
    "totalUnfilledPlacements": 55388,
    "unfilledUserOptOut": 0,
    "unfilledNotEnoughDemand": 0,
    "unfilledTotalAuctionSettings": 0,
    "unfilledTotalAuctionConsiderations": 0,
    "unfilledAdvertiserAuctionSettings": 0,
    "unfilledRetailerAuctionSettings": 0,
    "unfilledCriteoAuctionSettings": 0,
    "unfilledReturnedButNotPainted": 0,
    "nonDeliverableUnmappedCategories": 0,
    "nonDeliverablePagesWithUnknownProducts": 8,
    "nonDeliverableBlockedOptOut": 0,
    "nonDeliverableBlockedPageCategory": 0,
    "nonDeliverableInactivePlacement": null,
    "nonDeliverableInsufficientOrganicResults": 0,
    "nonDeliverableInvalidTraffic": null,
    "nonDeliverableTestPlacement": 0,
    "uncoveredUnusedFormats": null,
    "uncoveredSearchTermWithoutCategory": 5954,
    "uncoveredNoDemandBrandedKeywordConquestingEnabled": 0,
    "uncoveredNoDemandBrandedKeywordConquestingDisabled": 760,
    "uncoveredNoDemandUnbrandedInventory": 48666,
    "uncoveredNoDemandOptOut": 0,
    "uncoveredFilteredOutDemand": 0,
    "uncoveredBrokenPlacement": 0,
    "uncoveredNotPainted": null,
    "availablePlacements": 55388,
    "fillRate": null,
    "placementImpressions": null,
    "productImpressions": null,
    "placementClicks": null,
    "productClicks": null,
    "clicks": null,
    "placementImpressionsCTR": null,
    "productImpressionsCTR": null,
    "cpm": null,
    "cpc": null,
    "placementImpressionsRevenue": 0,
    "productClicksRevenue": 0,
    "revenue": null,
    "nonDeliverablePlacements": 8,
    "deliverablePlacements": 55380,
    "placementsWithCandidates": 0,
    "coveredPlacements": 0,
    "coverageRate": 0
  }
]
```

***

## Responses

<table>
  <thead>
    <tr>
      <th>
        <p>
          Response
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          🟢

          <code>
            200
          </code>
        </p>
      </td>

      <td>
        <p>
          Call executed with success
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          Common Validation Errors:
        </p>

        <ul>
          <li>
            <b>
              Deserialization error
            </b>

            : one or more input parameters is not supported; see details for more info.
          </li>

          <li>
            <b>
              Please select an interval under 100 days
            </b>

            : using a date range with more than 100 days apart between

            <code>
              startDate
            </code>

            and

            <code>
              endDate
            </code>

            .
          </li>

          <li>
            <b>
              Time zone xyz is not valid
            </b>

            : using a time zone value that is not listed in the list TZ database time zones.
          </li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            403
          </code>
        </p>
      </td>

      <td>
        <ul>
          <li>
            <b>
              You are not authorized to access some of the requested resources.
            </b>

            : API user does not have the authorization to access some of the requested resources. Review the supply account IDs used in the request and, for an authorization request, follow the <a href="/retail-media/docs/authorization-requests">authorization request</a> steps.
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

***

<br />

## What's next

* [Metrics & Dimensions (Fill Rate Report)](/retail-media/docs/metrics-dimensions-fill-rate-report)