---
title: library_placement_list
description: 'List the Placements of your Library: the global Placements of AdCrunch and the Placements of your organization.'
---

Ask which slots your Library knows. The agent lists the Placements that your organization sees, newest first. A Placement is the slot where a provider shows an ad, for example Meta Stories video, with rules that an Asset should hold.

> "Which placements do we have for Meta?"

The agent calls this tool, and filters by channel, by type, or by group. It calls the tool again for each next page until the list ends. You see each Placement with its rules. A global Placement belongs to AdCrunch, and nobody can change it. A Placement of the Library is not the placement of an ad that Meta reports: that one is a part of the performance data.

This tool is part of the job [Bring your own creative](/mcp/tools/bring-your-own-creative).

## Reference

List the Placements that the active organization's Library holds: the global Placements of AdCrunch and the Placements that your organization created, newest first. A Placement is the slot where a provider shows an ad, for example Meta Stories video. It holds rules that an Asset should hold to fit the slot. The rules are advice: they never block a write. Filter by `channel`, by `type`, or by `group_id` to read the Placements of one group. A global Placement has `isGlobal` true, and you cannot change it. Use library_placement_get to read one Placement. The answer holds at most `limit` rows (default 100, maximum 500). When it carries `nextCursor`, more rows exist: call this tool again with the same arguments and `cursor` set to that value. When it carries no `nextCursor`, you have every row.

### Input

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `channel` | one of `meta`, `tiktok`, `snapchat`, `google_search`, `google_pmax`, `google_display`, `youtube`, `programmatic_display`, `linkedin`, `x` | no | The channel of a Line Item that the slot belongs to. `type` and `channel` never change after the create. |
| `group_id` | string | no | The id of a Placement group (plg_…). library_placement_group_list gives it. |
| `type` | one of `image`, `video` | no | The kind of Asset that the slot takes. A slot that takes both has two Placements. `type` and `channel` never change after the create. |
| `cursor` | string, at least 1 character | no | The `nextCursor` of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 `invalid_cursor`. Do not build or change a cursor. |
| `limit` | integer, 1 to 500 | no | The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with `error` of `invalid_request`. Default: `100`. |

### Output

A successful call returns this object in `structuredContent`.

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `nextCursor` | string | no | Send this value as `cursor` to get the next page. It is absent on the last page. |
| `placements` | array of object | yes | The Placements of this page, newest first, each with its rules in `params` and `isGlobal`. A deleted Placement is not in the list. |
| `placements[].channel` | one of `meta`, `tiktok`, `snapchat`, `google_search`, `google_pmax`, `google_display`, `youtube`, `programmatic_display`, `linkedin`, `x` | yes | The channel of a Line Item that the Placement belongs to. It never changes. |
| `placements[].createdAt` | number | yes | Milliseconds since the Unix epoch, UTC. |
| `placements[].createdBy` | string or null | yes | The user who created the Placement. `null` on a global row. |
| `placements[].deletedAt` | number or null | yes | Always `null` here. A deleted Placement is not answered. |
| `placements[].description` | string or null | yes | A free text. `null` when the Placement has none. |
| `placements[].id` | string | yes | The id of the Placement, `plm_…`. |
| `placements[].isGlobal` | boolean | yes | `true` on a row that AdCrunch holds for every organization. You read it, and you cannot change or delete it. |
| `placements[].name` | string | yes | The name, 1 to 80 characters. It is unique, ignoring case, among the Placements of the channel that the organization sees. |
| `placements[].organizationId` | string or null | yes | The organization that owns the Placement. `null` on a global row. |
| `placements[].params` | object | yes |  |
| `placements[].params.type` | `image` or `video` | yes |  |
| `placements[].params.rules` | array of object, at most 20 items | yes | Only when `type` is `image`. |
| `placements[].params.rules[].type` | `width` or `height` or `size` or `ratio` or `mime` | yes |  |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `width`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `height`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `size`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `ratio`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (array of any, 2 items), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `mime`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | array of (string, 1 to 255 characters), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules` | array of object, at most 20 items | yes | Only when `type` is `video`. |
| `placements[].params.rules[].type` | `width` or `height` or `size` or `ratio` or `mime` or `duration` | yes |  |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `width`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `height`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `size`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `ratio`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | array of any, 2 items | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (array of any, 2 items), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `mime`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | string, 1 to 255 characters | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | array of (string, 1 to 255 characters), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].params.rules[].operator` | object | yes | Only when `type` is `duration`. |
| `placements[].params.rules[].operator.condition` | `eq` or `ne` or `lt` or `lte` or `gt` or `gte` or `in` | yes |  |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `eq`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `ne`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `lte`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gt`. |
| `placements[].params.rules[].operator.value` | integer, at least 0 | yes | Only when `condition` is `gte`. |
| `placements[].params.rules[].operator.value` | array of (integer, at least 0), 1 to 50 items | yes | Only when `condition` is `in`. |
| `placements[].type` | one of `image`, `video` | yes | The kind of Asset that the slot takes. It never changes, and it equals `params.type`. |
| `placements[].updatedAt` | number or null | yes | When the Placement last changed. `null` until its first update. |

### Failure codes

A failed call has `isError` set, and `structuredContent.error` holds one of these codes. [Errors](/mcp/errors) describes the shape of a failed call.

- `invalid_cursor`
- `not_found`
- `organization_unentitled`
- `forbidden`
- `invalid_request`
- `internal_error`

### Scope

The token must hold `library:read`. [Auth & scopes](/mcp/auth) lists each scope.

### Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

- **Read-only.** The tool changes nothing.
- **Closed world.** The tool reads and writes the data of AdCrunch only.

### Example

The arguments:

```json
{
  "channel": "meta",
  "limit": 20
}
```

The result, in `structuredContent`:

```json
{
  "placements": [
    {
      "channel": "meta",
      "createdAt": 1790000500000,
      "createdBy": "usr_2e5b84",
      "deletedAt": null,
      "description": "Our own cut for Reels, never over 30 seconds.",
      "id": "plm_4b8d27",
      "isGlobal": false,
      "name": "Reels short cut",
      "organizationId": "org_3a7f10",
      "params": {
        "rules": [
          {
            "operator": {
              "condition": "eq",
              "value": [
                9,
                16
              ]
            },
            "type": "ratio"
          },
          {
            "operator": {
              "condition": "lte",
              "value": 30000
            },
            "type": "duration"
          }
        ],
        "type": "video"
      },
      "type": "video",
      "updatedAt": null
    },
    {
      "channel": "meta",
      "createdAt": 1789000000000,
      "createdBy": null,
      "deletedAt": null,
      "description": null,
      "id": "plm_meta_stories_video",
      "isGlobal": true,
      "name": "Meta Stories video",
      "organizationId": null,
      "params": {
        "rules": [
          {
            "operator": {
              "condition": "eq",
              "value": [
                9,
                16
              ]
            },
            "type": "ratio"
          },
          {
            "operator": {
              "condition": "gte",
              "value": 250
            },
            "type": "width"
          },
          {
            "operator": {
              "condition": "in",
              "value": [
                "video/mp4",
                "video/quicktime"
              ]
            },
            "type": "mime"
          },
          {
            "operator": {
              "condition": "gte",
              "value": 1000
            },
            "type": "duration"
          }
        ],
        "type": "video"
      },
      "type": "video",
      "updatedAt": null
    }
  ]
}
```
