---
url: https://docs.dataflair.ai/marketplace/ad-server-api/operations/inventory.md
description: >-
  The cursor-paginated list of ad slots DataFlair maps placements to. Each slot
  has a stable inventory_id.
---

# GET /inventory: List bookable ad slots

DataFlair calls this endpoint to learn about your ad slots. An operator then maps DataFlair placements to your `inventory_id` values without copying ids by hand. For what an `inventory_id` is, see [Inventory identity](/marketplace/ad-server-api/inventory).

## What we send

::: code-group

```http [HTTP]
GET /inventory?limit=100&cursor=eyJsYXN0X2lkIjoic2xvdF80MTAifQ HTTP/1.1
Host: ads.example.com
Authorization: Bearer sk_live_9f2c…
```

```bash [curl]
curl "$BASE_URL/inventory?limit=100" \
  -H "Authorization: Bearer $API_KEY"
```

:::

| Query parameter | Required | Meaning |
| --- | --- | --- |
| `limit` | no | Page size. Default 50, minimum 1, maximum 200. |
| `cursor` | no | The opaque cursor from the previous response's `next_cursor`. |

When DataFlair connects your platform, it calls `GET /inventory?limit=1`. It needs only a successful answer with a `data` array to confirm the `inventory_read` capability.

## What you return

Status `200` with a JSON body:

::: code-group

```json \[exemplary/inventory/expected-response.json]
{
  "data": [
    {
      "inventory_id": "slot_728x90_home",
      "name": "Homepage Leaderboard",
      "sizes": [
        "728x90",
        "970x250"
      ],
      "format": "display",
      "status": "active"
    },
    {
      "inventory_id": "slot_300x250_article",
      "name": "Article MPU",
      "sizes": [
        "300x250"
      ],
      "format": "display",
      "status": "active"
    }
  ],
  "next_cursor": "eyJsYXN0X2lkIjoic2xvdF8zMDAifQ"
}

```

:::

The JSON on this page is read from the [fixture files](/marketplace/ad-server-api/fixtures), so it cannot drift from the test suite.

## Fields

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `data` | array | yes | The slots on this page. |
| `data[].inventory_id` | string | yes | The stable, opaque id described on [Inventory identity](/marketplace/ad-server-api/inventory). |
| `data[].name` | string | yes | A human label shown to the operator while mapping. |
| `data[].sizes` | array of strings | yes | Accepted creative sizes, each as `WIDTHxHEIGHT`, for example `728x90`. DataFlair uses them for size compatibility checks. |
| `data[].format` | string | no | `display`, `video`, `native` and so on. Free-form, so keep it consistent across slots. |
| `data[].status` | string | no | `active` or `archived`, so DataFlair can hide dead slots. |
| `next_cursor` | string or null | no | The cursor for the next page. Leave it out, or return `null`, on the last page. |

Paging follows the cursor rules in [Conventions](/marketplace/ad-server-api/conventions#pagination). Read `next_cursor` until it is absent.

## Errors

| Status | What caused it | What DataFlair does | What to do |
| --- | --- | --- | --- |
| `400` | Malformed request. | Treats it as a bug, logs it and shows it. | Check the query parameters. |
| `401` | Missing, invalid or expired key. | Marks the connection as `error`. The operator re-checks the credential. | Check the key. |
| `403` | The key lacks a required scope. | Marks the connection as `error`. The operator widens the scope. | Give the key read scope. |
| `429` | Rate limit exceeded. | Backs off and retries per `Retry-After`. | Send a `Retry-After` header in seconds. |
| `5xx` | Server error. | Retries with backoff. A persistent `5xx` shows as "your platform is unreachable". | Check your server's logs. |

Today, DataFlair calls this endpoint in one place: the connect step, with `limit=1`. A failure there does not fail the connection. It leaves Inventory read as **Not verified**. The reactions in the table come from the contract in [Conventions](/marketplace/ad-server-api/conventions#http-status-usage).

Every error body has the shape described in [Conventions](/marketplace/ad-server-api/conventions#error-model).

## Timeouts and retries

DataFlair waits up to 10 seconds to connect and 30 seconds in total for this call. These are the platform's configured defaults. DataFlair does not retry a failed `GET /inventory` probe.

## Verify

Run the [conformance check](/marketplace/ad-server-api/conformance) with `--only inventory` to check this endpoint against the [fixtures](/marketplace/ad-server-api/fixtures).