Fill Rate Report

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.

VerbEndpointDescription
POST/reports/fillrateRequest a fill rate report creation
POST/reports/unfilled-placementsRequest an unfilled reasons report
GET/reports/{reportId}/statusGet status of a specific report
GET/reports/{reportId}/outputDownload output of a specific report

Report Request Attributes

Attribute

Data Type

Description

supplyAccountIds*

list<string>

Supply Account IDs to pull results for

Accepted values: array of strings/int64
Writable? N / Nullable? N

dimensions*

list<enum>

An array of strings used to define which dimensions to see in the report

Accepted values: refer to Metrics and Dimensions for the complete list of supported dimensions
Writable? N / Nullable? N

metrics*

list<enum>

An array of strings used to define which metrics to see in the report

Accepted values: refer to Metrics and Dimensions for the complete list of supported metrics
Writable? N / Nullable? N

startDate*

date

Start date of the report (inclusive)

Accepted values: yyyy-mm-dd with max interval of 100 days with endDate
Writable? N / Nullable? N

endDate*

date

End date of the report (inclusive)

Accepted values: yyyy-mm-dd with max interval of 100 days with startDate
Writable? N / Nullable? N

timezone

string

Time zone to consider in the metrics calculation,startDate and endDate

Accepted values: IANA (TZ database) time zones (example: America/New_York, Europe/Paris, Asia/Tokyo, UTC)
Default: UTC
Writable? N / Nullable? Y

format

enum

The format type the report should return results

Accepted values: json, json-compact, json-newline, csv
Default: json
Writable? N / Nullable? N

adServerType

enum

The ad server responsible for rending the ad on the retailer site.

Accepted values: all, gam, criteo

📘

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.

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

https://api.criteo.com/preview/retail-media/reports/fillrate

Sample Request

curl -X 'POST' \
  'https://api.criteo.com/preview/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)

{
  "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

https://api.criteo.com/preview/retail-media/reports/unfilled-placements

Sample Request

📘

List of Unfilled Reasons

Check the full list of supported unfilled reasons here

curl -X 'POST' \
  'https://api.criteo.com/preview/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

{
  "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.

https://api.criteo.com/preview/retail-media/reports/{reportId}/status

Sample Request

curl -L 'https://api.criteo.com/preview/retail-media/reports/5f148e12-fba3-432e-b0d5-fe316xxxxx/status' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response

{
    "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.

https://api.criteo.com/preview/retail-media/reports/{reportId}/output

Sample Request

curl -X GET "https://api.criteo.com/preview/retail-media/reports/2e733b8c-9983-4237-aab9-17a4xxxxxx/output" \
-H "Authorization: Bearer <MY_ACCESS_TOKEN>"

Sample Responses

Fill Rate and Coverage Rate

[
 {
    "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

[
  {
    "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

Response

Description

🟢 200

Call executed with success

🔴 400

Common Validation Errors:

  • Deserialization error: one or more input parameters is not supported; see details for more info.
  • Please select an interval under 100 days: using a date range with more than 100 days apart between startDate and endDate.
  • Time zone xyz is not valid: using a time zone value that is not listed in the list TZ database time zones.

🔴 403

  • You are not authorized to access some of the requested resources.: 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 authorization request steps.