List pins
list_pinsRead-onlyIdempotent
List pins in this workspace, newest first, with search, filters and sorting.
Use to find a pin's id (search its title with q), review what published
or failed, or audit one board or account. For one known pin use
get_pin; for scheduled (not yet published) pins use list_schedules; for
totals over a period use get_dashboard_summary.
Returns one page: {items, total, limit, offset, has_more}. items are
pin summaries (id, title, status, board_id, pinterest_account_id,
pinterest_pin_id, link_url, error_code, error_message, created_at,
published_at, removed_from_pinterest_at); detail="full" returns every
field, but read one pin with get_pin instead. removed=true lists
published pins that were deleted on Pinterest. total counts every match
across all pages, so "how many pins failed this week?" is one call with
status=failed, since=... and limit=1. To read further, repeat the call
with the same filters, q and sort and offset = offset + limit while
has_more is true. total is null only against a PinBridge API older
than 1.34. Filtering on an account
outside the key's allow-list fails with account_not_permitted, and an
unknown sort or status fails with validation_error.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Case-insensitive text to find in the title, description or link URL; % and _ match literally. | |
| sort | No | Order: created_at, published_at (unpublished last), title or status, each _asc or _desc. | created_at_desc |
| limit | No | Page size, 1-200. | |
| since | No | ISO 8601 timestamp with timezone; lower bound, inclusive. | |
| until | No | ISO 8601 timestamp with timezone; upper bound, exclusive. | |
| detail | No | summary (default): the fields needed to find, audit and count pins. full: the whole pin, including description, alt text and media URLs; about three times larger, so prefer get_pin for one pin. | summary |
| offset | No | Rows to skip. For the next page pass offset + limit from the last result. | |
| status | No | One of queued, deferred, publishing, published, failed. | |
| removed | No | true: only published pins that were later deleted on Pinterest; false: leave them out. Default: both. | |
| board_id | No | Pinterest board ID (numeric string), from list_boards. | |
| account_id | No | UUID of a connected Pinterest account, from list_pinterest_accounts. | |
| error_code | No | Only failed pins with this error code, e.g. board_access_denied. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Pins on this page in the requested order. With detail=summary each has id, title, status, board_id, pinterest_account_id, pinterest_pin_id, link_url, error_code, error_message, created_at, published_at and removed_from_pinterest_at (set when the pin was deleted on Pinterest). detail=full returns every pin field. Empty when nothing matches. | |
| limit | Yes | Page size used for this call. | |
| total | Yes | How many rows match the filters and search across all pages. Answer "how many ...?" from this; limit=1 is enough. Null only when the PinBridge API is older than 1.34. | |
| offset | Yes | Rows skipped before this page. | |
| has_more | Yes | true when more rows follow: call again with the same filters, q and sort and offset = offset + limit. When total is null it only means this page was full. |