Skip to content
AdCrunch
Esc
↑↓navigate↵open⌘Jpreview
On this page

library_placement_list

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.

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 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 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:

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

The result, in structuredContent:

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

Was this page helpful?