Fill Rate Report - Criteo Docs

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.

Verb	Endpoint	Description
POST	`/reports/fillrate`	Request a fill rate report creation
POST	`/reports/unfilled-placements`	Request an unfilled reasons report
GET	`/reports/{reportId}/status`	Get status of a specific report
GET	`/reports/{reportId}/output`	Download output of a specific report

Report Request Attributes

Attribute	Data Type	Description
`supplyAccountIds`*	list	Supply Account IDs to pull results for\nAccepted values: array of strings/int64\nWritable? N / Nullable? N
`dimensions`*	list	An array of strings used to define which dimensions to see in the report\nAccepted values: refer to Metrics and Dimensions for the complete list of supported dimensions\nWritable? N / Nullable? N
`metrics`*	list	An array of strings used to define which metrics to see in the report\nAccepted values: refer to Metrics and Dimensions for the complete list of supported metrics\nWritable? N / Nullable? N
`startDate`*	date	Start date of the report (inclusive)\nAccepted values:`yyyy-mm-dd`with max interval of 100 days with`endDate`\nWritable? N / Nullable? N
`endDate`*	date	End date of the report (inclusive)\nAccepted values:`yyyy-mm-dd`with max interval of 100 days with`startDate`\nWritable? N / Nullable? N
`timezone`	string	Time zone to consider in the metrics calculation,`startDate`and`endDate`\nAccepted values: IANA (TZ database) time zones (example:`America/New_York`,`Europe/Paris`,`Asia/Tokyo`,`UTC`)\nDefault:`UTC`\nWritable? N / Nullable? Y
`format`	enum	The format type the report should return results\nAccepted values:`json`,`json-compact`,`json-newline`,`csv`\nDefault:`json`\nWritable? N / Nullable? N
`adServerType`	enum	The ad server responsible for rendering the ad on the retailer site.\nAccepted 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 Sample Request

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 '{\n  "data": {\n    "type": "string",\n    "attributes": {\n      "supplyAccountIds": [\
        "8639134211138xxxx"\
      ],\n      "dimensions": [\
          "date",\
          "retailerId",\
          "retailerName",\
          "placementId",\
          "placementName",\
          "pageTypeName",\
          "environment",\
          "servedCategory",\
          "retailerCategoryId",\
          "retailerCategoryName",\
          "adServerType"\
      ],\n      "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"\
                ],\n      "adServerType": "all",\n      "format": "csv",\n      "startDate": "2025-09-08",\n      "endDate": "2025-09-09",\n      "timezone": "America/New_York"\n    }\n  }\n}'

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/{version}/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/{version}/retail-media/reports/unfilled-placements' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json-patch+json' \
  -H 'Authorization: Bearer Add Token' \
  -d '{\n  "data": {\n    "type": "string",\n    "attributes": {\n      "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"\n    }\n  }\n}'

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. Sample Request

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

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

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

[
 { 
    "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:\n- Deserialization error: one or more input parameters is not supported; see details for more info.\n- Please select an interval under 100 days: using a date range with more than 100 days apart between`startDate`and`endDate`.\n- 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.

What’s next

Metrics & Dimensions (Fill Rate Report)