library_placement_group_list
List the Placement groups of your Library: the global groups of AdCrunch and the groups of your organization.
Ask how your Placements are grouped. The agent lists the Placement groups, newest first. A group is a named set of Placements, for example all the Placements of one channel. A global group holds global Placements only.
“Which placement groups do we have?”
The agent calls this tool, and calls it again for each next page. To see the Placements of one group, it calls library_placement_group_get.
This tool is part of the job Bring your own creative.
Reference
List the Placement groups of the active organization’s Library: the global groups of AdCrunch, one for each channel that has Placements, and the groups that your organization created. Newest first. A Placement group is a named set of Placements, for example all the Placements of one channel. A group has no channel and no rules. A group of your organization holds global Placements and Placements of your organization. A global group holds global Placements only. 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. Use library_placement_group_get to read one group with its Placements. 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 |
|---|---|---|---|
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 |
|---|---|---|---|
groups |
array of object | yes | The groups of this page, newest first, each with isGlobal and no Placement. A deleted group is not in the list. library_placement_group_get reads the Placements of one group. |
groups[].createdAt |
number | yes | Milliseconds since the Unix epoch, UTC. |
groups[].createdBy |
string or null | yes | The user who created the group. null on a global row. |
groups[].deletedAt |
number or null | yes | Always null here. A deleted group is not answered. |
groups[].description |
string or null | yes | A free text. null when the group has none. |
groups[].id |
string | yes | The id of the group, plg_…. |
groups[].isGlobal |
boolean | yes | true on a row that AdCrunch holds for every organization. You read it, and you cannot change or delete it. |
groups[].name |
string | yes | The name, 1 to 80 characters. It is unique, ignoring case, among the groups that the organization sees. |
groups[].organizationId |
string or null | yes | The organization that owns the group. null on a global row. |
groups[].updatedAt |
number or null | yes | When the group last changed. null until its first update. |
nextCursor |
string | no | Send this value as cursor to get the next page. It is absent on the last page. |
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_cursororganization_unentitledforbiddeninvalid_requestinternal_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:
{
"limit": 20
}
The result, in structuredContent:
{
"groups": [
{
"createdAt": 1790000600000,
"createdBy": "usr_2e5b84",
"deletedAt": null,
"description": null,
"id": "plg_9e1c53",
"isGlobal": false,
"name": "Vertical video",
"organizationId": "org_3a7f10",
"updatedAt": null
},
{
"createdAt": 1789000000000,
"createdBy": null,
"deletedAt": null,
"description": null,
"id": "plg_meta",
"isGlobal": true,
"name": "Meta",
"organizationId": null,
"updatedAt": null
}
]
}