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

library_placement_group_add

Add one Placement to a Placement group of your organization.

Ask to put a Placement in a group. The agent adds one Placement to a group of your organization. The Placement can be global or a Placement of your organization, of any channel.

“Put Meta Reels video in the Vertical group.”

A Placement that the group already holds changes nothing, and the call still succeeds. You see the group with its Placements.

This tool is part of the job Bring your own creative.

Reference

Add one Placement to a Placement group of your organization. The Placement can be a global Placement or a Placement of your organization, of any channel. The answer is the group with its Placements after the call. A Placement that the group already holds changes nothing, and the call still succeeds. A global row (isGlobal is true) is held by AdCrunch for each organization. You read it and use it. A change of a global row, and a delete of it, answer not_found.

Input

Argument Type Required Description
group_id string yes The id of a Placement group (plg_…). library_placement_group_list gives it.
placement_id string yes The id of a Placement (plm_…). library_placement_list gives it. A Placement of AdCrunch (isGlobal) and a Placement of your organization both work.

Output

A successful call returns this object in structuredContent.

Field Type Always present Description
group object yes The group after the call, with every Placement that it holds.
group.createdAt number yes Milliseconds since the Unix epoch, UTC.
group.createdBy string or null yes The user who created the group. null on a global row.
group.deletedAt number or null yes Always null here. A deleted group is not answered.
group.description string or null yes A free text. null when the group has none.
group.id string yes The id of the group, plg_….
group.isGlobal boolean yes true on a row that AdCrunch holds for every organization. You read it, and you cannot change or delete it.
group.name string yes The name, 1 to 80 characters. It is unique, ignoring case, among the groups that the organization sees.
group.organizationId string or null yes The organization that owns the group. null on a global row.
group.updatedAt number or null yes When the group last changed. null until its first update.
group.placements array of object yes Every live Placement that the group holds, with no page. A group holds at most the Placements that the organization sees.
group.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.
group.placements[].createdAt number yes Milliseconds since the Unix epoch, UTC.
group.placements[].createdBy string or null yes The user who created the Placement. null on a global row.
group.placements[].deletedAt number or null yes Always null here. A deleted Placement is not answered.
group.placements[].description string or null yes A free text. null when the Placement has none.
group.placements[].id string yes The id of the Placement, plm_….
group.placements[].isGlobal boolean yes true on a row that AdCrunch holds for every organization. You read it, and you cannot change or delete it.
group.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.
group.placements[].organizationId string or null yes The organization that owns the Placement. null on a global row.
group.placements[].params object yes
group.placements[].params.type image or video yes
group.placements[].params.rules array of object, at most 20 items yes Only when type is image.
group.placements[].params.rules[].type width or height or size or ratio or mime yes
group.placements[].params.rules[].operator object yes Only when type is width.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is eq.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is ne.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lte.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (integer, at least 0), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is height.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is eq.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is ne.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lte.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (integer, at least 0), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is size.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is eq.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is ne.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lte.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (integer, at least 0), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is ratio.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is eq.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is ne.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is lt.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is lte.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is gt.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (array of any, 2 items), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is mime.
group.placements[].params.rules[].operator.condition eq or ne or in yes
group.placements[].params.rules[].operator.value string, 1 to 255 characters yes Only when condition is eq.
group.placements[].params.rules[].operator.value string, 1 to 255 characters yes Only when condition is ne.
group.placements[].params.rules[].operator.value array of (string, 1 to 255 characters), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules array of object, at most 20 items yes Only when type is video.
group.placements[].params.rules[].type width or height or size or ratio or mime or duration yes
group.placements[].params.rules[].operator object yes Only when type is width.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is eq.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is ne.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lte.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (integer, at least 0), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is height.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is eq.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is ne.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lte.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (integer, at least 0), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is size.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is eq.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is ne.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lte.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (integer, at least 0), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is ratio.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is eq.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is ne.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is lt.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is lte.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is gt.
group.placements[].params.rules[].operator.value array of any, 2 items yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (array of any, 2 items), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is mime.
group.placements[].params.rules[].operator.condition eq or ne or in yes
group.placements[].params.rules[].operator.value string, 1 to 255 characters yes Only when condition is eq.
group.placements[].params.rules[].operator.value string, 1 to 255 characters yes Only when condition is ne.
group.placements[].params.rules[].operator.value array of (string, 1 to 255 characters), 1 to 50 items yes Only when condition is in.
group.placements[].params.rules[].operator object yes Only when type is duration.
group.placements[].params.rules[].operator.condition eq or ne or lt or lte or gt or gte or in yes
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is eq.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is ne.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is lte.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gt.
group.placements[].params.rules[].operator.value integer, at least 0 yes Only when condition is gte.
group.placements[].params.rules[].operator.value array of (integer, at least 0), 1 to 50 items yes Only when condition is in.
group.placements[].type one of image, video yes The kind of Asset that the slot takes. It never changes, and it equals params.type.
group.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.

  • not_found
  • organization_unentitled
  • forbidden
  • invalid_request
  • internal_error

Scope

The token must hold library:write. 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.

  • Writes. The tool can change data.
  • Not destructive. The tool makes only additive changes.
  • Idempotent. A second call with the same arguments changes nothing more.
  • Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "group_id": "plg_9e1c53",
  "placement_id": "plm_meta_stories_video"
}

The result, in structuredContent:

{
  "group": {
    "createdAt": 1790000600000,
    "createdBy": "usr_2e5b84",
    "deletedAt": null,
    "description": null,
    "id": "plg_9e1c53",
    "isGlobal": false,
    "name": "Vertical video",
    "organizationId": "org_3a7f10",
    "updatedAt": null,
    "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?