> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal): > ```bash > npx -y @scalekit-inc/cli setup -y > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup -y > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to Pinterest The Pinterest connector lets your AI agent act in each user's Pinterest account. Each user signs in to Pinterest once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 72 tools. **Authentication:** OAuth 2.0 **Categories:** Media, Marketing **Tools:** 72: 50 read, 19 write, 3 destructive **Users sign in with:** OAuth **OAuth app:** Your own Pinterest app **Built by:** Scalekit connector **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=PINTEREST) ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Create the Pinterest connection In **AgentKit > Connections**, create a Pinterest connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/). 4. ### Register an OAuth app Pinterest connections use your own OAuth app. Register one with Pinterest and add the redirect URI you copied. Then enter the app's Client ID and Client Secret on the Pinterest connection. 5. ### Authorize a user and make your first call **Node.js** (`quickstart.mts`) ```typescript import { ScalekitClient } from '@scalekit-sdk/node' import 'dotenv/config' import { createInterface } from 'node:readline/promises' const scalekit = new ScalekitClient( process.env.SCALEKIT_ENVIRONMENT_URL, process.env.SCALEKIT_CLIENT_ID, process.env.SCALEKIT_CLIENT_SECRET, ) const actions = scalekit.actions const connector = 'pinterest' const identifier = 'user_123' // Generate an authorization link for the user const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier }) console.log('Authorize Pinterest:', link) const rl = createInterface({ input: process.stdin, output: process.stdout }) await rl.question('Press Enter after authorizing...') rl.close() // Make your first call const result = await actions.executeTool({ connector, identifier, toolName: 'pinterest_boards_list', toolInput: {}, }) console.log(result) ``` ```bash npx tsx quickstart.mts ``` **Python** (`quickstart.py`) ```python import os from scalekit import ScalekitClient from dotenv import load_dotenv load_dotenv() scalekit_client = ScalekitClient( env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), ) actions = scalekit_client.actions connection_name = "pinterest" identifier = "user_123" # Generate an authorization link for the user link_response = actions.get_authorization_link( connection_name=connection_name, identifier=identifier, ) print("Authorize Pinterest:", link_response.link) input("Press Enter after authorizing...") # Make your first call result = actions.execute_tool( tool_input={}, tool_name="pinterest_boards_list", connection_name=connection_name, identifier=identifier, ) print(result) ``` ```bash python quickstart.py ``` Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses. ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'pinterest_board_get', toolInput: { board_id: '', }, connector: 'pinterest', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="pinterest_board_get", tool_input={ "board_id": "", }, connection_name="pinterest", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `pinterest_board_get` Get Board · Read-only Get a single board by its ID from the authenticated Pinterest account, or a group board shared with that account. Returns the board's full details: id, name, description, privacy, pin count, follower count, and media. Use this to fetch one specific board when you already know its ID. Use pinterest_boards_list instead to browse or find boards. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board to retrieve. Digits only. Example: 549755885175. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access to view a board owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"board_id":""}` ### `pinterest_board_pins_list` List Pins on Board · Read-only List the Pins saved to a specific board owned by the authenticated Pinterest account, or a group board shared with that account. Returns a page of Pin objects (id, title, description, link, media, board_id) as items, plus a bookmark cursor for the next page (null when no more pages remain). Use this to browse or paginate the Pins on a board you already know the ID of. Use pinterest_pin_get to fetch one specific Pin's full details by ID, or pinterest_board_sections_list to see the board's sections instead of its Pins directly. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board whose Pins to list. Digits only. Example: 549755885175. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this listing, instead of the token user's own account. Only needed when using Pinterest Business Access to view Pins owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor used to fetch the next page of items. Pass the bookmark value returned in a previous response's "bookmark" field. Omit or leave null for the first page. - `creative_types` (`array`, optional): Filter Pins by ad creative type. Array of one or more of: REGULAR, VIDEO, SHOPPING, CAROUSEL, MAX_VIDEO, COLLECTION, IDEA, SHOWCASE, QUIZ, COLLAGE, MAX_WIDTH_REGULAR_COLLECTION, MAX_WIDTH_VIDEO_COLLECTION, APP. Note: SHOP_THE_PIN is deprecated in favor of COLLECTION. - `page_size` (`integer`, optional): Maximum number of Pins to return in a single page. Integer from 1 to 250. Defaults to 25. Default: `25`. - `pin_metrics` (`boolean`, optional): Whether to include 90-day and lifetime Pin engagement metrics (impressions, saves, clicks, comments, reactions) in the response. Total comments and total reactions are only available with lifetime metrics. Defaults to false. Default: `false`. Example input: `{"board_id":""}` ### `pinterest_board_section_pins_list` List Pins in Board Section · Read-only List the Pins within a specific section of a board owned by the authenticated Pinterest account, or a group board shared with that account. Returns a page of Pin objects (id, title, description, link, media, board_id, board_section_id) as items, plus a bookmark cursor for the next page (null when no more pages remain). Use this to browse the Pins inside one section. Use pinterest_board_pins_list instead to list all Pins on the whole board, or pinterest_board_sections_list to find a section_id first. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board that owns the section. Digits only. Example: 549755885175. - `section_id` (`string`, required): The unique numeric identifier of the board section whose Pins to list. Digits only. Example: 907186624124. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this listing, instead of the token user's own account. Only needed when using Pinterest Business Access to view Pins owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor used to fetch the next page of items. Pass the bookmark value returned in a previous response's "bookmark" field. Omit or leave null for the first page. - `page_size` (`integer`, optional): Maximum number of Pins to return in a single page. Integer from 1 to 250. Defaults to 25. Default: `25`. Example input: `{"board_id":"","section_id":""}` ### `pinterest_board_sections_list` List Board Sections · Read-only List all sections on a board owned by the authenticated Pinterest account, or a group board shared with that account. Returns a page of section objects (id, name) as items, plus a bookmark cursor for the next page (null when no more pages remain). Use this to browse a board's sections, e.g. to find a section_id. Use pinterest_board_section_pins_list instead to see the Pins inside one section, or pinterest_board_pins_list for all Pins on the board. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board whose sections to list. Digits only. Example: 549755885175. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this listing, instead of the token user's own account. Only needed when using Pinterest Business Access to view sections on a board owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor used to fetch the next page of items. Pass the bookmark value returned in a previous response's "bookmark" field. Omit or leave null for the first page. - `page_size` (`integer`, optional): Maximum number of sections to return in a single page. Integer from 1 to 250. Defaults to 25. Default: `25`. Example input: `{"board_id":""}` ### `pinterest_boards_list` List Boards · Read-only List the boards owned by the authenticated Pinterest account, plus group boards it collaborates on, optionally filtered by privacy level. Returns a page of board objects (id, name, description, privacy, pin count, follower count) as items, plus a bookmark cursor for the next page (null when no more pages remain). Use this to browse or search your boards, e.g. to find a board_id. Use pinterest_board_get instead to fetch one board you already know the ID of. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this listing, instead of the token user's own account. Only needed when using Pinterest Business Access to view boards owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor used to fetch the next page of items. Pass the bookmark value returned in a previous response's "bookmark" field. Omit or leave null for the first page. - `page_size` (`integer`, optional): Maximum number of boards to return in a single page. Integer from 1 to 250. Defaults to 25. Default: `25`. - `privacy` (`string`, optional): Filter boards by privacy level. One of: ALL, PUBLIC, PROTECTED, SECRET, PUBLIC_AND_SECRET. If omitted, all boards visible to the token's scopes (and the ad account role, if applicable) are returned. One of: `ALL`, `PUBLIC`, `PROTECTED`, `SECRET`, `PUBLIC_AND_SECRET`. Example input: `{}` ### `pinterest_boards_search` Search Boards · Read-only Search the authenticated Pinterest account's boards by keyword, or by a comma-separated list of Pin IDs. Returns a page of matching board objects (name, description, privacy, owner, and more) plus a bookmark cursor for the next page. Use this to find boards by keyword; leave query blank to list all of the account's boards instead. Use pinterest_pins_search instead to search Pins rather than boards. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this search, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor returned as "bookmark" in a previous response. Pass it to fetch the next page of boards. Omit or leave blank to fetch the first page. Example: LTE5NTMxNjUzMTQyMzE2NDkwMDM. - `page_size` (`integer`, optional): Maximum number of boards to return in a single page. Integer between 1 and 250. Defaults to 25. Default: `25`. - `query` (`string`, optional): Search query. Can contain board description keywords or comma-separated Pin IDs. Leave blank to list all of the account's boards. Example: home decor. Example input: `{}` ### `pinterest_catalog_feed_get` Get Catalog Feed · Read-only Get a single Pinterest catalog feed by its ID, from the authenticated account or a Business Access ad account you manage. Returns the feed's full details: name, format, location, status, catalog_type, default locale/country/currency, and credentials/processing schedule if set. Use this to check a feed's configuration when you already know its feed_id. Use catalog_feeds_list to browse or find a feed_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `feed_id` (`string`, required): The unique numeric identifier of the catalog feed to retrieve. Digits only. Example: 864344156814050986. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"feed_id":""}` ### `pinterest_catalog_feed_processing_results_list` List Catalog Feed Processing Results · Read-only List the processing results from past ingestion runs of a Pinterest catalog feed, including product/video counts and validation errors or warnings. Returns a page of processing-result objects (id, status, ingestion_details, product_counts, video_counts, validation_details) and a bookmark cursor for the next page. Use this to check whether a feed_id's ingestion succeeded and to see item-level validation issues. Note: Pinterest currently only returns the first page for this endpoint; the bookmark cursor is not yet functional. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `feed_id` (`string`, required): The unique numeric identifier of the catalog feed whose processing results you want to list. Digits only. Example: 864344156814050986. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor from a previous response's bookmark field. Currently not functional for this endpoint (only the first page is returned), but accepted for forward compatibility. - `page_size` (`integer`, optional): Maximum number of processing results to return in a single page. Between 1 and 250. Defaults to 25. Default: `25`. Example input: `{"feed_id":""}` ### `pinterest_catalog_feeds_list` List Catalog Feeds · Read-only List Pinterest catalog feeds owned by the authenticated account, or by a Business Access ad account you manage, optionally filtered to one catalog. Returns a page of feed objects (id, name, format, location, status, catalog_type) and a bookmark cursor for the next page. Use this to browse feeds or find a feed_id before calling catalog_feed_get, catalog_feed_update, or catalog_feed_ingest. Pass catalog_id to scope results to one catalog. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor from a previous response's bookmark field. Pass it to fetch the next page of feeds. Omit to get the first page. - `catalog_id` (`string`, optional): Filter feeds to only those belonging to this catalog. If omitted, feeds from all catalogs are returned. Digits only. Example: 864344156814050986. - `page_size` (`integer`, optional): Maximum number of feeds to return in a single page. Between 1 and 250. Defaults to 25. Default: `25`. Example input: `{}` ### `pinterest_catalog_filter_values_list` List Catalog Filter Values · Read-only List the product filter attributes and sample values available for a Pinterest catalog, optionally scoped to one feed, country, or language. Returns a catalog_type-specific filter_values map (e.g. brand, availability, custom labels) sampled from up to 1000 items; not guaranteed to include every value in the catalog. Use this to discover valid filter values before building product group rules for a catalog. Requires an existing catalog_id from catalogs_list or catalog_create. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_id` (`string`, required): The unique numeric identifier of the catalog to inspect. Digits only. Example: 864344156814050986. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `country` (`string`, optional): ISO 3166-1 alpha-2 country code to scope the filter values to. Only used for retail catalogs. Example: US. - `feed_id` (`string`, optional): Unique identifier of a specific catalog feed to scope the filter values to. If omitted, all feeds in the catalog are considered. Digits only. Example: 864344156814050986. - `language` (`string`, optional): Locale code to scope the filter values to. Only used for retail catalogs. Example: en-US. One of: `af-ZA`, `ar-SA`, `bg-BG`, `bn-IN`, `cs-CZ`, `da-DK`, `de`, `el-GR`, `en-AU`, `en-CA`, `en-GB`, `en-IN`, `en-US`, `es-419`, `es-AR`, `es-ES`, `es-MX`, `fi-FI`, `fr`, `fr-CA`, `he-IL`, `hi-IN`, `hr-HR`, `hu-HU`, `id-ID`, `it`, `ja`, `ko-KR`, `ms-MY`, `nb-NO`, `nl`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sv-SE`, `te-IN`, `th-TH`, `tl-PH`, `tr`, `uk-UA`, `vi-VN`, `zh-CN`, `zh-TW`. Example input: `{"catalog_id":""}` ### `pinterest_catalog_item_issues_list` List Catalog Item Issues · Read-only List item-level validation issues found while processing a Pinterest catalog feed, for a given feed processing result. Returns up to 20 sampled affected items per issue code, each with the item number, issue code, and message; results are paginated with a bookmark. Use this after a feed upload to see what's wrong with individual items. For a complete, non-sampled list of every affected item, use the catalogs reports endpoints instead. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `processing_result_id` (`string`, required): Unique identifier of a feed processing result. Get it from the id field of the List processing results for a given feed response. Digits only. Example: 6114941667693520896. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor from a previous response's bookmark field. Omit on the first call to start from the beginning. - `item_numbers` (`array`, optional): Filter to specific item numbers, based on order of appearance in the catalog feed (e.g. 0 is the first item found in the feed). Cannot be combined with item_validation_issue in the same request. - `item_validation_issue` (`string`, optional): Filter to item validation issues of this specific issue code (e.g. AVAILABILITY_INVALID, DESCRIPTION_MISSING, GTIN_INVALID). Cannot be combined with item_numbers in the same request. - `page_size` (`integer`, optional): Maximum number of issues to include in a single page. Defaults to 25, maximum 250. Default: `25`. Example input: `{"processing_result_id":""}` ### `pinterest_catalog_items_batch_get` Get Catalog Items Batch Status · Read-only Get the status and results of a Pinterest catalog items batch write by its batch ID. Returns the batch's catalog_type, processing status (PROCESSING, COMPLETED, FAILED), created/completed timestamps, and per-item processing records with any validation errors or warnings. Use this to poll a batch started by pinterest_catalog_items_batch_create until it finishes. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `batch_id` (`string`, required): Unique identifier of the catalog items batch operation to check, returned by pinterest_catalog_items_batch_create. Digits only. Example: 595953100599279259. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"batch_id":""}` ### `pinterest_catalog_items_list` List Catalog Items · Read-only Fetch items from a Pinterest product catalog using a filter, such as a list of item IDs, scoped by catalog type (RETAIL, HOTEL, or CREATIVE_ASSETS), country, and language. Returns the matching items with their attributes, images, and Pinterest processing status. Use this when you already know which item IDs to look up. Use pinterest_catalog_items_batch_create to create, update, or delete items, and pinterest_catalog_items_batch_get to check the status of a batch write. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `country` (`string`, required): ISO 3166-1 alpha-2 country code that scopes the catalog lookup. Example: US. - `filters` (`object`, required): Filter object identifying which items to return, discriminated by catalog_type. For a RETAIL catalog: {"catalog_type": "RETAIL", "item_ids": ["DS0294-M"], "catalog_id": ""} (item_ids is required, up to 1000 IDs). HOTEL and CREATIVE_ASSETS catalogs use their own filter shapes — see Pinterest's Catalogs API reference. - `language` (`string`, required): Language/locale for the catalog items, as a BCP-47 or Pinterest CatalogsLocale code. Example: en-US. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"country":"","filters":{},"language":""}` ### `pinterest_catalog_local_inventory_items_list` Query Local Inventory Items · Read-only Look up local inventory items — store-specific stock and price overrides — for a Pinterest catalog, by a list of item_id and store_code pairs (up to 1000 pairs). Returns the matching local inventory items with their store-specific attributes. Use this to check current local inventory records. Use pinterest_catalog_local_inventory_items_batch_create to create, update, upsert, or delete them. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_id` (`string`, required): Unique identifier of the catalog to query local inventory items in. Digits only, up to 19 characters. - `item_filters` (`string`, required): JSON array of up to 1000 {item_id, store_code} pairs identifying which local inventory items to fetch. Both fields are required on every pair. Example: [{"item_id": "item_id_1", "store_code": "store_1"}]. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"catalog_id":"","item_filters":""}` ### `pinterest_catalog_local_stores_list` List Local Stores · Read-only List local, brick-and-mortar stores registered for a Pinterest catalog, optionally filtered to specific store IDs. Returns each store's id, store_code, name, address, coordinates, and country; results are paginated with a bookmark. Use this to browse or look up existing stores. Use pinterest_catalog_local_stores_create to add new ones. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_id` (`string`, required): Unique identifier of the catalog whose local stores you want to list. Digits only, up to 19 characters. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor from a previous response's bookmark field. Omit on the first call to start from the beginning. - `local_store_ids` (`string`, optional): Comma-separated list of local store IDs to filter by. Omit to list all stores for the catalog. Example: 1234567890,2345678901. - `page_size` (`integer`, optional): Maximum number of stores to include in a single page. Defaults to 25, maximum 250. Default: `25`. Example input: `{"catalog_id":""}` ### `pinterest_catalog_product_group_get` Get Catalog Product Group · Read-only Get a single catalog product group by its ID from the authenticated Pinterest account, or from a Business Access ad account you manage. Returns the product group's ID, name, catalog association, and filter configuration. Use this to fetch one specific product group when you already know its ID. Use pinterest_catalog_product_groups_list instead to browse or filter product groups. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `product_group_id` (`string`, required): The unique numeric identifier of the catalog product group to retrieve. Digits only. Example: 2680059592705. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"product_group_id":""}` ### `pinterest_catalog_product_group_product_counts_get` Get Catalog Product Group Product Counts · Read-only Get the number of matching, pending, and total products for a single catalog product group. Returns product counts for the given product group (fields vary by catalog type, e.g. total, approved, processing, and rejected item counts). Use this to check how many catalog items a product group's filters currently match, for example to verify a filter change took effect. Requires the product group's ID from pinterest_catalog_product_group_create or pinterest_catalog_product_groups_list. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `product_group_id` (`string`, required): The unique numeric identifier of the catalog product group to get product counts for. Digits only. Example: 2680059592705. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"product_group_id":""}` ### `pinterest_catalog_product_group_products_list` List Catalog Product Group Products · Read-only List the catalog products (Pins) that belong to a specific catalog product group. Returns a page of matching catalog products with their item details plus a bookmark cursor for the next page. Use this to see which specific items a product group's filters currently match. Use pinterest_catalog_products_by_filter_list instead to preview matches for a filter set before creating a product group. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `product_group_id` (`string`, required): The unique numeric identifier of the catalog product group whose products you want to list. Digits only. Example: 2680059592705. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this listing, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor returned as 'bookmark' in a previous response. Pass it to fetch the next page of results. Omit for the first page. - `page_size` (`integer`, optional): Maximum number of products to return in a single page. Between 1 and 250. Defaults to 25. Default: `25`. - `pin_metrics` (`boolean`, optional): Whether to include 90-day and lifetime Pin engagement metrics in the response for each returned product's Pin. Defaults to false. Default: `false`. Example input: `{"product_group_id":""}` ### `pinterest_catalog_product_groups_list` List Catalog Product Groups · Read-only List catalog product groups in the authenticated Pinterest account, optionally filtered by specific product group IDs, a feed ID, or a catalog ID. Returns a page of product groups (ID, name, catalog association, and filters) plus a bookmark cursor for the next page. Use this to browse or filter existing product groups. Use pinterest_catalog_product_group_get instead when you already know a single product group's ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this listing, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor returned as 'bookmark' in a previous response. Pass it to fetch the next page of results. Omit for the first page. - `catalog_id` (`string`, optional): Filter results to product groups belonging to a given catalog_id. If omitted, product groups from all catalogs are considered. Numeric string. Example: 2680059592705. - `feed_id` (`string`, optional): Filter results to product groups belonging to a given feed_id. If omitted, product groups from all feeds are considered. Numeric string. Example: 2680059592705. - `page_size` (`integer`, optional): Maximum number of product groups to return in a single page. Between 1 and 250. Defaults to 25. Default: `25`. - `product_group_ids` (`string`, optional): Comma-separated list of up to 1000 product group IDs to restrict the results to. If omitted, all product groups (subject to the other filters) are returned. Example: 2680059592705,2680059592706. Example input: `{}` ### `pinterest_catalog_products_by_filter_list` Preview Catalog Products By Filter · Read-only Preview which catalog products would match a given product-group filter, without creating a product group. Supports a feed-based filter (feed_id + filters) or a catalog/vertical-based filter for RETAIL, HOTEL, or CREATIVE_ASSETS catalogs (catalog_id + catalog_type + filters). Returns a page of matching catalog products plus a bookmark cursor for the next page. Use this to test and refine a filters object before calling pinterest_catalog_product_group_create or pinterest_catalog_product_group_update. Read only: yes. Destructive: no. Idempotent (safe to retry): no. Inputs: - `filters` (`object`, required): Object holding the filter criteria to preview matches for. Shape: {"any_of": []} to match items satisfying ANY listed criterion, or {"all_of": []} to require ALL of them. Each filter key object has one key (e.g. ITEM_ID, MIN_PRICE, BRAND, AVAILABILITY, CUSTOM_LABEL_0) whose value is a criteria object, typically {"values": [...]} and optionally {"negated": true}. Cannot be empty. Example: {"any_of": [{"ITEM_ID": {"values": ["123456789"]}}]}. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this preview, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor returned as 'bookmark' in a previous response. Pass it to fetch the next page of results. Omit for the first page. - `catalog_id` (`string`, optional): Catalog ID to preview matches against. Required, together with catalog_type, when previewing a catalog/vertical-based filter instead of a feed-based one. Numeric string. Example: 2680059592705. - `catalog_type` (`string`, optional): Selects a catalog/vertical-based filter preview instead of a feed-based one. When set, catalog_id is required and feed_id must be omitted. RETAIL additionally requires country and locale. Valid values: RETAIL, HOTEL, CREATIVE_ASSETS. Omit entirely to preview a feed-based filter with feed_id instead. One of: `RETAIL`, `HOTEL`, `CREATIVE_ASSETS`. - `country` (`string`, optional): ISO 3166-1 alpha-2 country code to preview matches against. Required, together with locale, when catalog_type is RETAIL; not used for HOTEL, CREATIVE_ASSETS, or feed-based filters. Two-letter code. Example: US. - `feed_id` (`string`, optional): Catalog Feed ID to preview matches against. Required when previewing a feed-based filter, i.e. when catalog_type is omitted. Must be omitted when catalog_type is set. Numeric string. Example: 2680059592705. - `locale` (`string`, optional): Locale to preview matches against. Required, together with country, when catalog_type is RETAIL; not used for HOTEL, CREATIVE_ASSETS, or feed-based filters. Format: language-COUNTRY or language. Example: en-US. - `page_size` (`integer`, optional): Maximum number of products to return in a single page. Between 1 and 250. Defaults to 25. Default: `25`. - `pin_metrics` (`boolean`, optional): Whether to include 90-day and lifetime Pin engagement metrics in the response for each returned product's Pin. Defaults to false. Default: `false`. Example input: `{"filters":{}}` ### `pinterest_catalog_report_get` Get Catalog Report · Read-only Get the status and download URL for a catalogs report previously started with pinterest_catalog_report_create, using the token it returned. Returns report_status (FINISHED or IN_PROGRESS), and once finished, a URL to download the report file and its size in bytes. Use this to retrieve a report after starting it. The report is built asynchronously, so poll this tool with the same token until report_status is FINISHED before using the URL. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `token` (`string`, required): The token returned by pinterest_catalog_report_create when the report build was started. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"token":""}` ### `pinterest_catalog_report_stats_list` List Catalog Report Stats · Read-only List aggregated issue counts (feed ingestion issues or distribution issues) for a RETAIL or HOTEL catalog you own. This is independent of pinterest_catalog_report_create/pinterest_catalog_report_get — it does not use a report token. Returns a page of aggregated stat items (counts by issue type) plus a bookmark cursor for the next page. Use this to check catalog health at a glance without waiting for a full report to build via pinterest_catalog_report_create. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `parameters` (`object`, required): Object identifying which catalog and issue type to aggregate stats for. Always include catalog_type (RETAIL or HOTEL) and a report object with report_type: FEED_INGESTION_ISSUES (requires feed_id, optional processing_result_id) or DISTRIBUTION_ISSUES. Example: {"catalog_type": "RETAIL", "report": {"report_type": "FEED_INGESTION_ISSUES", "feed_id": "2680059592705"}}. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this listing, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor returned as 'bookmark' in a previous response. Pass it to fetch the next page of results. Omit for the first page. - `page_size` (`integer`, optional): Maximum number of stat items to return in a single page. Between 1 and 250. Defaults to 25. Default: `25`. Example input: `{"parameters":{}}` ### `pinterest_catalog_supplemental_items_batch_get` Get Supplemental Items Batch Status · Read-only Get the status and results of a Pinterest supplemental items batch operation, such as a local inventory items batch, for a catalog. Returns the batch's status (PROCESSING, COMPLETED, FAILED) and, once complete, per-operation results including any validation errors or warnings. Use this to poll a batch started by pinterest_catalog_local_inventory_items_batch_create until it finishes. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `batch_id` (`string`, required): Unique identifier of the supplemental items batch operation to check, returned by pinterest_catalog_local_inventory_items_batch_create. Example: 66753b9bb65c46c49bd. - `catalog_id` (`string`, required): Unique identifier of the catalog the batch operation belongs to. Digits only, up to 19 characters. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"batch_id":"","catalog_id":""}` ### `pinterest_catalogs_list` List Catalogs · Read-only List catalogs owned by the authenticated Pinterest account, or by a Business Access ad account you manage. Returns a page of catalog objects (id, name, catalog_type, created_at, updated_at) and a bookmark cursor for the next page. Use this to browse existing catalogs or find a catalog_id before creating a catalog feed. Use catalog_create to add a new catalog. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor from a previous response's bookmark field. Pass it to fetch the next page of catalogs. Omit to get the first page. - `page_size` (`integer`, optional): Maximum number of catalogs to return in a single page. Between 1 and 250. Defaults to 25. Default: `25`. Example input: `{}` ### `pinterest_media_get` Get Media Upload · Read-only Get the status and details of a previously registered Pinterest media upload by its media_id. Returns media_id, media_type, and status (one of registered, processing, succeeded, or failed). Use this to poll a video upload's processing status after registering it with pinterest_media_create and separately uploading the file bytes, before referencing the media in a Pin. Use pinterest_media_list instead to browse media uploads rather than looking up one you already have the ID for. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `media_id` (`string`, required): The unique numeric identifier of the media upload to retrieve, as returned by pinterest_media_create. Digits only. Example: 12345. Example input: `{"media_id":""}` ### `pinterest_media_list` List Media Uploads · Read-only List Pinterest media uploads registered by the authenticated account. Returns a page of media upload objects (media_id, media_type, status) plus a bookmark cursor for the next page, or a null bookmark when there are no more results. Use this to browse all media uploads rather than looking up one by ID with pinterest_media_get. Pass the previous response's bookmark value as the bookmark input to fetch the next page. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `bookmark` (`string`, optional): Pagination cursor returned as "bookmark" in a previous response. Pass it to fetch the next page of media uploads. Omit or leave blank to fetch the first page. Example: LTE5NTMxNjUzMTQyMzE2NDkwMDM. - `page_size` (`integer`, optional): Maximum number of media uploads to return in a single page. Integer between 1 and 250. Defaults to 25. Default: `25`. Example input: `{}` ### `pinterest_pin_analytics_get` Get Pin Analytics · Read-only Get performance analytics for a single Pin owned by the authenticated Pinterest account, or on a group board shared with that account, over a date range up to 90 days. Returns a time series (and optional per-app-type split) of the requested metric values, keyed by metric type and date. Use this to measure how one specific Pin is performing. Use pinterest_pins_analytics_list instead to get analytics for multiple Pins in a single call. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `end_date` (`string`, required): End date (UTC) of the metric report, format YYYY-MM-DD. Cannot be more than 90 days after start_date. Example: 2026-08-27. - `metric_types` (`string`, required): Pin metric types to fetch, as a comma-separated list. Standard Pins support: IMPRESSION, OUTBOUND_CLICK, PIN_CLICK, SAVE, SAVE_RATE, TOTAL_COMMENTS, TOTAL_REACTIONS, USER_FOLLOW, PROFILE_VISIT. Video Pins additionally support: VIDEO_MRC_VIEW, VIDEO_10S_VIEW, QUARTILE_95_PERCENT_VIEW, VIDEO_V50_WATCH_TIME, VIDEO_START, VIDEO_AVG_WATCH_TIME. Cannot request video-only metrics together with split_field set to anything other than NO_SPLIT. Example: IMPRESSION,PIN_CLICK,SAVE. - `pin_id` (`string`, required): The unique numeric identifier of the Pin to get analytics for. Digits only. Example: 526931230485217455. - `start_date` (`string`, required): Start date (UTC) of the metric report, format YYYY-MM-DD. Cannot be more than 90 days back from today. Example: 2026-05-29. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access to view analytics for a Pin owned by that ad account's user; the token user must hold an appropriate Business Access role (Admin or Analyst) on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `app_types` (`string`, optional): Apps or devices to get data for. One of: ALL, MOBILE, TABLET, WEB. Defaults to ALL. One of: `ALL`, `MOBILE`, `TABLET`, `WEB`. Default: `ALL`. - `split_field` (`string`, optional): How to split the returned data into groups. One of: NO_SPLIT, APP_TYPE. Defaults to NO_SPLIT. Cannot be set to a value other than NO_SPLIT if metric_types includes ALL. One of: `NO_SPLIT`, `APP_TYPE`. Default: `NO_SPLIT`. Example input: `{"end_date":"","metric_types":"","pin_id":"","start_date":""}` ### `pinterest_pin_get` Get Pin · Read-only Get a single Pin by its ID from the authenticated Pinterest account, or from a Business Access ad account you manage. Returns the Pin's full details: title, description, link, alt text, media, board ID, and creation metadata. Use this to fetch one specific Pin when you already know its ID. Use a Pins list or search tool instead to browse or find Pins by board or query. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `pin_id` (`string`, required): The unique numeric identifier of the Pin to retrieve. Digits only. Example: 526931230485217455. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access to view a Pin owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `pin_metrics` (`boolean`, optional): Whether to include 90-day and lifetime Pin engagement metrics (impressions, saves, clicks, comments, reactions) in the response. Total comments and total reactions are only available with lifetime metrics. Defaults to false. Default: `false`. Example input: `{"pin_id":""}` ### `pinterest_pin_product_tags_list` List Pin Product Tags · Read-only Retrieve all product tags currently on a hero Pin. Returns an array of product tags (each with the tagged product Pin's ID); the array is empty if the Pin has no product tags. Use this to check which product Pins are tagged onto a hero Pin before adding or removing tags. Use pinterest_pin_product_tags_add or pinterest_pin_product_tags_delete to change the tags. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `pin_id` (`string`, required): The unique numeric identifier of the hero Pin whose product tags to list. Digits only. Example: 526931230485217455. Example input: `{"pin_id":""}` ### `pinterest_pins_analytics_list` List Pins Analytics · Read-only Get performance analytics for up to 100 Pins at once, owned by the authenticated Pinterest account or on a group board shared with that account, over a date range up to 90 days. Returns an object keyed by Pin ID, each value containing that Pin's requested metric values over the date range. Use this to compare or bulk-report on many Pins in a single call. Use pinterest_pin_analytics_get instead when you only need analytics for one Pin. This endpoint is currently in beta and not available to all Pinterest apps. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `end_date` (`string`, required): End date (UTC) of the metric report, format YYYY-MM-DD. Cannot be more than 90 days after start_date. Example: 2026-08-27. - `metric_types` (`string`, required): Pin metric types to fetch, as a comma-separated list. Valid values: IMPRESSION, OUTBOUND_CLICK, PIN_CLICK, SAVE, SAVE_RATE, TOTAL_COMMENTS, TOTAL_REACTIONS, USER_FOLLOW, PROFILE_VISIT, VIDEO_MRC_VIEW, VIDEO_10S_VIEW, QUARTILE_95_PERCENT_VIEW, VIDEO_V50_WATCH_TIME, VIDEO_START, VIDEO_AVG_WATCH_TIME. Example: IMPRESSION,PIN_CLICK,SAVE. - `pin_ids` (`string`, required): Pin IDs to get analytics for, as a comma-separated list of digit-only IDs. Up to 100 IDs per request. Example: 526931230485217455,526931230485217456. - `start_date` (`string`, required): Start date (UTC) of the metric report, format YYYY-MM-DD. Cannot be more than 90 days back from today. Example: 2026-05-29. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Only needed when using Pinterest Business Access to view analytics for Pins owned by that ad account's user; the token user must hold an appropriate Business Access role (Admin or Analyst) on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `app_types` (`string`, optional): Apps or devices to get data for. One of: ALL, MOBILE, TABLET, WEB. Defaults to ALL. One of: `ALL`, `MOBILE`, `TABLET`, `WEB`. Default: `ALL`. Example input: `{"end_date":"","metric_types":"","pin_ids":"","start_date":""}` ### `pinterest_pins_list` List Pins · Read-only List the Pins owned by the authenticated Pinterest account, or by a Business Access ad account you manage, across all of that account's boards. Returns a page of Pin objects (id, title, description, link, media, board_id) as items, plus a bookmark cursor for the next page (null when no more pages remain). Use this to browse or paginate all of an account's Pins regardless of which board they're on. Use pinterest_board_pins_list instead when you already know the board and only want its Pins. Use pinterest_pin_get to fetch one specific Pin's full details by ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this listing, instead of the token user's own account. Only needed when using Pinterest Business Access to view Pins owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor used to fetch the next page of items. Pass the bookmark value returned in a previous response's "bookmark" field. Omit or leave null for the first page. - `creative_types` (`array`, optional): Filter Pins by ad creative type. Array of one or more of: REGULAR, VIDEO, SHOPPING, CAROUSEL, MAX_VIDEO, COLLECTION, IDEA, SHOWCASE, QUIZ, COLLAGE, MAX_WIDTH_REGULAR_COLLECTION, MAX_WIDTH_VIDEO_COLLECTION, APP. Note: SHOP_THE_PIN is deprecated in favor of COLLECTION. - `domain` (`string`, optional): Only return Pins whose link matches this exact domain (no "www." prefix). Example: pinterest.com. - `domains` (`array`, optional): Only return Pins whose link's domain matches any value in this list. Array of up to 100 domain strings. Example: ["instagram.com", "jcpenney.com"]. - `include_product_tag_obj` (`boolean`, optional): Whether to include product tag objects (with their associated links) in the response. Defaults to false. - `include_protected_pins` (`boolean`, optional): Whether to include protected (limited-visibility) Pins in the results. Defaults to false. Default: `false`. - `page_size` (`integer`, optional): Maximum number of Pins to return in a single page. Integer from 1 to 250. Defaults to 25. Default: `25`. - `pin_filter` (`string`, optional): Filter to apply to the returned Pins. One of: exclude_native (exclude Pins created directly on Pinterest), exclude_repins (exclude Pins saved from other Pins), has_been_promoted (only Pins that have been used as ads). One of: `exclude_native`, `exclude_repins`, `has_been_promoted`. - `pin_metrics` (`boolean`, optional): Whether to include 90-day and lifetime Pin engagement metrics (impressions, saves, clicks, comments, reactions) in the response. Total comments and total reactions are only available with lifetime metrics. Defaults to false. Default: `false`. - `pin_type` (`string`, optional): The type of Pins to return. Currently only enabled for private Pins. Valid value: PRIVATE. One of: `PRIVATE`. Example input: `{}` ### `pinterest_pins_search` Search Pins · Read-only Search the authenticated Pinterest account's Pins by keyword, or by a comma-separated list of Pin IDs. Returns a page of matching Pin objects (title, description, link, board_id, media, and more) plus a bookmark cursor for the next page. Use this when you need to find Pins by a text query. Use pinterest_pin_get instead to fetch one specific Pin when you already know its ID, or pinterest_boards_search to search boards rather than Pins. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `query` (`string`, required): Search query. Can contain Pin description keywords or comma-separated Pin IDs. Required by this endpoint. Example: home decor. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this search, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Pagination cursor returned as "bookmark" in a previous response. Pass it to fetch the next page of Pins. Omit or leave blank to fetch the first page. Example: LTE5NTMxNjUzMTQyMzE2NDkwMDM. Example input: `{"query":""}` ### `pinterest_terms_related_list` List Related Terms · Read-only Get search terms logically related to one or more input terms, the same way Pinterest's own related-search suggestions work. Returns id (the first input term), related_term_count, and related_terms_list, an array pairing each input term with its list of related terms. Use this to expand a seed keyword (e.g. 'workout') into related terms (e.g. 'yoga workout', 'workout motivation') for content ideas or ad targeting. Use pinterest_terms_suggested_list instead for autocomplete-style suggestions from a single partial term. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `terms` (`string`, required): One or more input terms to get related terms for, as a comma-separated string (no spaces around commas needed). The first term in the list is echoed back as "id" in the response. Example: clothes,workout. Example input: `{"terms":""}` ### `pinterest_terms_suggested_list` List Suggested Terms · Read-only Get popular Pinterest search terms that begin with a given input term (autocomplete-style suggestions). Returns an array of suggested search term strings, e.g. searching 'sport' returns terms like 'sports bar' and 'sportswear' but not 'motor sports' since it must start with the input term. Use this to autocomplete or expand a single partial keyword. Use pinterest_terms_related_list instead to find terms conceptually related to one or more full input terms, not just ones sharing a prefix. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `term` (`string`, required): The input term to get suggestions for. Only terms starting with this string are returned. Example: sport. - `limit` (`integer`, optional): Maximum number of suggested terms to return. Integer between 1 and 10. Defaults to 4. Default: `4`. Example input: `{"term":""}` ### `pinterest_trends_editorial_articles_list` List Editorial Trend Articles · Read-only List Pinterest's published editorial trend articles for a geographic region. Returns an array of articles, each with a title, description, related interests, related keywords, board URL, and related pin URLs; translated into the region's language when available, English otherwise. Use this to browse Pinterest's curated trend write-ups for content and campaign planning. Use the trending keywords, product categories, or featured topics tools instead for raw trend metrics rather than editorial content. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `region` (`string`, required): The geographic region of interest. Only editorial trend articles published for this region are returned. Formatted as ISO 3166-2 country codes, with multi-country regions delimited by '+'. Valid values: US, GB+IE (Great Britain & Ireland), CA. Example: GB+IE. One of: `US`, `GB+IE`, `CA`. Example input: `{"region":"US"}` ### `pinterest_trends_keywords_list` List Trending Keywords · Read-only List the top trending search keywords among the Pinterest user audience for a region and trend type. Returns an ordered array of trending keywords, each with the keyword text, week-over-week / month-over-month / year-over-year percent growth, a normalized search-volume time series, and optional age/gender demographics. Use this to inform ad targeting, budget strategy, and creative decisions. Use the trend product categories or featured topics tools instead for shopping-category or interest-level trend data rather than raw keywords. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `region` (`string`, required): The geographic region of interest. Only top trends within this region are returned. Formatted as ISO 3166-2 country codes, with multi-country regions delimited by '+'. Valid values: US, CA, DE, FR, ES, IT, DE+AT+CH (Germanic countries), GB+IE (Great Britain & Ireland), IT+ES+PT+GR+MT (Southern Europe), PL+RO+HU+SK+CZ (Eastern Europe), SE+DK+FI+NO (Nordic countries), NL+BE+LU (Benelux), AR, BR, CO, MX, MX+AR+CO+CL (Hispanic LatAm), AU+NZ (Australasia). Example: GB+IE. One of: `US`, `CA`, `DE`, `FR`, `ES`, `IT`, `DE+AT+CH`, `GB+IE`, `IT+ES+PT+GR+MT`, `PL+RO+HU+SK+CZ`, `SE+DK+FI+NO`, `NL+BE+LU`, `AR`, `BR`, `CO`, `MX`, `MX+AR+CO+CL`, `AU+NZ`. - `trend_type` (`string`, required): The methodology used to rank how trendy a keyword is. `growing` trends have high upward growth in search volume over the last quarter. `monthly` trends have high search volume in the last month. `yearly` trends have high search volume in the last year. `seasonal` trends have high upward growth in search volume over the last month and exhibit a seasonal recurring pattern (typically annual). One of: `growing`, `monthly`, `yearly`, `seasonal`. - `ages` (`array`, optional): If set, filters the results to trends among users in the specified age range(s). Valid values: 18-24, 25-34, 35-44, 45-49, 50-54, 55-64, 65+. If unset, trends among all age groups are returned. - `genders` (`array`, optional): If set, filters the results to trends among users who identify with the specified gender(s). Valid values: male, female, unknown (`unknown` includes users with unspecified or customized gender profile settings). If unset, trends among all genders are returned. - `include_demographics` (`boolean`, optional): Whether to include the age and gender distribution for each keyword in the response. By default (`false`), the response does not include demographics data. Default: `false`. - `include_keywords` (`array`, optional): If set, filters the results to top trends which include at least one of the specified keywords. If unset, no keyword filtering is applied. Between 1 and 50 keywords, each up to 100 characters. Example: ["recipes", "dessert"]. - `interests` (`array`, optional): If set, filters the results to trends among users who follow the specified interest categories. Valid values: animals, architecture, art, beauty, childrens_fashion, design, diy_and_crafts, education, electronics, entertainment, event_planning, finance, food_and_drinks, gardening, health, home_decor, mens_fashion, parenting, quotes, sport, travel, vehicles, wedding, womens_fashion. If unset, trends among all interests are returned. - `limit` (`integer`, optional): The maximum number of trending keywords to return. Keywords are returned in trend-ranked order, so a limit of 50 returns the top 50 trends. Defaults to 50, maximum 50, minimum 1. Default: `50`. - `normalize_against_group` (`boolean`, optional): Governs how the resulting time series data is normalized to a [0-100] scale. By default (`false`), the data is normalized independently for each keyword, so the peak search volume observation in each keyword's time series is 100. If set to `true`, the data is normalized as a group so the peak observation across all keywords in the response is 100, enabling comparison of relative search volume between multiple keywords. Default: `false`. Example input: `{"region":"US","trend_type":"growing"}` ### `pinterest_trends_product_categories_get` Get Product Category Trend Details · Read-only Get demographic information, related searches, and trend lines for specific Pinterest shopping product categories. Returns an array with one entry per requested category: age/gender demographics, engagement/outbound-click/save metric highlights, a normalized time series, related search terms, and an optional 90-day predicted time series. Use this when you already know the product category codes you want details for. Use pinterest_trends_product_categories_trending_list instead to discover which shopping categories are currently growing. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `product_categories` (`array`, required): List of Pinterest product category codes to retrieve trend details for. Between 1 and 20 categories. Valid values are Pinterest's fixed catalog of 383 product category codes (uppercase, underscore-separated), for example BEDDING, LIVING_ROOM_FURNITURE, or MENS_SNEAKERS. Example: ["BEDDING", "AREA_RUGS"]. - `region` (`string`, required): The geographic region of interest. Only trend details for product categories within this region are returned. Formatted as ISO 3166-2 country codes delimited by '+'. Valid values: US (United States), GB+IE (Great Britain & Ireland), CA (Canada). One of: `US`, `GB+IE`, `CA`. - `engagement_type` (`string`, optional): Type of engagement metric to analyze. Valid values: ENGAGEMENT (overall engagement metric), OUTBOUND_CLICK (number of outbound clicks), SAVE (number of pin saves). Defaults to ENGAGEMENT. One of: `ENGAGEMENT`, `OUTBOUND_CLICK`, `SAVE`. Default: `ENGAGEMENT`. - `lookback_window` (`integer`, optional): Time period for historical data analysis, in days. Defines how far back the API analyzes data to compute trend metrics. Valid values: 90 (last 90 days / 3 months), 180 (last 180 days / 6 months), 365 (last 365 days / 1 year), 730 (last 730 days / 2 years). Defaults to 365. One of: `90`, `180`, `365`, `730`. Default: `365`. Example input: `{"product_categories":["BEDDING","AREA_RUGS"],"region":"US"}` ### `pinterest_trends_product_categories_trending_list` List Trending Product Categories · Read-only List growing Pinterest shopping product categories in ranked order for a region, with optional vertical, age, and gender filters. Returns an array of product categories, each with the Pinterest product category ID and name, associated verticals, engagement type, month-over-month percent change, and relative volume percentage. Use this to discover which shopping categories are currently trending. Use pinterest_trends_product_categories_get instead when you already know the category codes and want full demographic and time-series detail for them. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `region` (`string`, required): The geographic region of interest. Only growing product categories within this region are returned. Formatted as ISO 3166-2 country codes delimited by '+'. Valid values: US (United States), GB+IE (Great Britain & Ireland), CA (Canada). One of: `US`, `GB+IE`, `CA`. - `ages` (`array`, optional): Age buckets to filter by. Valid values: 18-24, 25-34, 35-44, 45-49, 50-54, 55-64, 65+. If not provided, results are filtered by all ages. - `engagement_type` (`string`, optional): Type of engagement metric used to rank and analyze growing product categories. Valid values: ENGAGEMENT (overall engagement metric), OUTBOUND_CLICK (number of outbound clicks), SAVE (number of pin saves). Defaults to ENGAGEMENT. One of: `ENGAGEMENT`, `OUTBOUND_CLICK`, `SAVE`. Default: `ENGAGEMENT`. - `genders` (`array`, optional): Genders to filter by. Valid values: MALE, FEMALE, UNSPECIFIED. If not provided, results are filtered by all genders. - `verticals` (`array`, optional): List of verticals to filter growing product categories by. Valid values: FASHION, HOME_DECOR, BEAUTY. If unset, all verticals are included. Example input: `{"region":"US"}` ### `pinterest_trends_topics_featured_list` List Featured Trend Topics · Read-only List the top five featured Pinterest trend topics for an interest category and market, at parity with the Pinterest Trends UI. Returns an array with one entry per interest/market combination, each containing up to five trending topics with title, description, related interests and searches, a normalized time series, month-over-month growth percentage, and up to six representative pin images. Use this for a curated, editorial-style summary of what's trending in a specific interest. Use pinterest_trends_keywords_list instead for raw ranked search-keyword trend data. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `region` (`string`, required): The geographic region/market of interest. Only featured topics for this region are returned. Formatted as ISO 3166-2 country codes delimited by '+'. Valid values: US (United States), GB+IE (Great Britain & Ireland), CA (Canada). One of: `US`, `GB+IE`, `CA`. - `interest` (`string`, optional): Interest category to filter featured trend topics by. Valid values: ALL, ANIMALS, ARCHITECTURE, ART, BEAUTY, DIY_AND_CRAFTS, EDUCATION, EVENT_PLANNING, FASHION, FOOD_AND_DRINKS, GARDENING, HEALTH, HOME_DECOR, PARENTING, TRAVEL, WEDDING. If unset, featured topics across all interests are returned. One of: `ALL`, `ANIMALS`, `ARCHITECTURE`, `ART`, `BEAUTY`, `DIY_AND_CRAFTS`, `EDUCATION`, `EVENT_PLANNING`, `FASHION`, `FOOD_AND_DRINKS`, `GARDENING`, `HEALTH`, `HOME_DECOR`, `PARENTING`, `TRAVEL`, `WEDDING`. Example input: `{"region":"US"}` ### `pinterest_user_account_analytics_get` Get User Account Analytics · Read-only Get account-level engagement analytics for the connected Pinterest user account over a date range. Returns a map of the requested metric types (e.g. IMPRESSION, SAVE, ENGAGEMENT) to their aggregated values, optionally split by app type, content ownership, source, or Pin format. Use this for account-wide engagement totals. Use pinterest_user_account_top_pins_list or pinterest_user_account_top_video_pins_list instead to see performance broken out by individual Pins. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `end_date` (`string`, required): End date of the metric report window (UTC), inclusive. Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. Example: 2026-07-28. - `start_date` (`string`, required): Start date of the metric report window (UTC), inclusive. Format: YYYY-MM-DD. Cannot be more than 90 days before today. Example: 2026-07-01. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this request, instead of the token user's own account. Only needed when using Pinterest Business Access to view or report on data owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `app_types` (`string`, optional): Apps or devices to get data for, default is all. Valid values: ALL, MOBILE, TABLET, WEB. Defaults to ALL. One of: `ALL`, `MOBILE`, `TABLET`, `WEB`. Default: `ALL`. - `content_type` (`string`, optional): Filter to paid or organic data. Default is all. Valid values: ALL, PAID, ORGANIC. Defaults to ALL. One of: `ALL`, `PAID`, `ORGANIC`. Default: `ALL`. - `from_claimed_content` (`string`, optional): Filter on Pins that match your claimed domain. Valid values: OTHER, CLAIMED, BOTH. Defaults to BOTH. One of: `OTHER`, `CLAIMED`, `BOTH`. Default: `BOTH`. - `metric_types` (`array`, optional): Metric types to get data for. Valid values: ENGAGEMENT, ENGAGEMENT_RATE, IMPRESSION, OUTBOUND_CLICK, OUTBOUND_CLICK_RATE, PIN_CLICK, PIN_CLICK_RATE, SAVE, SAVE_RATE. Defaults to all metric types when omitted. Example: ["IMPRESSION", "SAVE"]. - `pin_format` (`string`, optional): Pin formats to get data for, default is all. Valid values: ALL, ORGANIC_IMAGE, ORGANIC_PRODUCT, ORGANIC_VIDEO, ADS_STANDARD, ADS_PRODUCT, ADS_VIDEO, ADS_IDEA. Defaults to ALL. One of: `ALL`, `ORGANIC_IMAGE`, `ORGANIC_PRODUCT`, `ORGANIC_VIDEO`, `ADS_STANDARD`, `ADS_PRODUCT`, `ADS_VIDEO`, `ADS_IDEA`. Default: `ALL`. - `source` (`string`, optional): Filter to activity from Pins created and saved by you, or activity created and saved by others from your claimed accounts. Default is all. Valid values: ALL, YOUR_PINS, OTHER_PINS. Defaults to ALL. One of: `ALL`, `YOUR_PINS`, `OTHER_PINS`. Default: `ALL`. - `split_field` (`string`, optional): How to split the returned analytics data into groups. Valid values: NO_SPLIT, APP_TYPE, OWNED_CONTENT, SOURCE, PIN_FORMAT. Not including this parameter (or leaving the default) means the data is not split into groups. One of: `NO_SPLIT`, `APP_TYPE`, `OWNED_CONTENT`, `SOURCE`, `PIN_FORMAT`. Default: `NO_SPLIT`. Example input: `{"end_date":"","start_date":""}` ### `pinterest_user_account_businesses_list` List Linked Businesses · Read-only List the business accounts linked to the connected Pinterest user account. Returns an array of linked businesses, each with a username and small/medium/large/x-large profile image URLs. Use this to see which business accounts the current user account is linked to. Use pinterest_user_account_get instead for the current account's own profile details. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `pinterest_user_account_followers_list` List Account Followers · Read-only List the users who follow the authenticated Pinterest account. Returns a page of follower objects (type, username) plus a bookmark token for the next page. Use this to see who follows your account. Use the following-users tool instead to see who the account follows. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `bookmark` (`string`, optional): Cursor token from a previous response's bookmark field, used to fetch the next page of followers. Omit or leave blank to start from the first page. - `page_size` (`integer`, optional): Maximum number of followers to return in a single page. Integer between 1 and 250. Defaults to 25. Default: `25`. Example input: `{}` ### `pinterest_user_account_following_boards_list` List Followed Boards · Read-only List the boards the authenticated Pinterest account follows. Returns a page of board summary objects plus a bookmark token for the next page. Use this to see which boards the account follows. Use the following-users tool instead to see which people the account follows. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Cursor token from a previous response's bookmark field, used to fetch the next page of boards. Omit or leave blank to start from the first page. - `explicit_following` (`boolean`, optional): Whether to return only boards explicitly followed by the user (true), or also include boards followed implicitly through followed users (false). Defaults to false. Default: `false`. - `page_size` (`integer`, optional): Maximum number of boards to return in a single page. Integer between 1 and 250. Defaults to 25. Default: `25`. Example input: `{}` ### `pinterest_user_account_following_list` List Followed Users · Read-only List the Pinterest users the authenticated account follows. Returns a page of followed-user objects (type, username) plus a bookmark token for the next page. Use this to see who the account follows. Use the followers-list tool instead to see who follows the account. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. - `bookmark` (`string`, optional): Cursor token from a previous response's bookmark field, used to fetch the next page of followed users. Omit or leave blank to start from the first page. - `explicit_following` (`boolean`, optional): Whether to return only explicitly followed users (true), or also include followees implied by board follows (false). Defaults to false. Default: `false`. - `feed_type` (`string`, optional): Which followee feed type to include. One of ALL, RANKED, CREATOR_ONLY, or RANKED_CREATOR_ONLY. Defaults to ALL (every followee type). One of: `ALL`, `RANKED`, `CREATOR_ONLY`, `RANKED_CREATOR_ONLY`. Default: `ALL`. - `page_size` (`integer`, optional): Maximum number of followed users to return in a single page. Integer between 1 and 250. Defaults to 25. Default: `25`. Example input: `{}` ### `pinterest_user_account_get` Get User Account · Read-only Get profile information for the connected Pinterest user account. Returns the account's username, account type, profile image, about text, business name, website, board count, pin count, follower and following counts, and monthly views. Use this to fetch the authenticated user's own account details, or a Business Access ad account's owner when ad_account_id is supplied. Use pinterest_user_account_analytics_get instead for engagement metrics rather than profile fields. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this request, instead of the token user's own account. Only needed when using Pinterest Business Access to view or report on data owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{}` ### `pinterest_user_account_top_pins_list` List Top Pins Analytics · Read-only List the connected Pinterest user account's top-performing Pins (up to the top 50) over a date range, ranked by a chosen metric. Returns per-metric data status plus, for each returned Pin, its Pin ID and a map of the requested metric values. Use this to see which individual Pins are driving the most engagement, saves, impressions, or clicks. Use pinterest_user_account_top_video_pins_list instead for video-specific metrics like watch time. Use pinterest_user_account_analytics_get instead for a single account-wide total rather than a per-Pin breakdown. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `end_date` (`string`, required): End date of the metric report window (UTC), inclusive. Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. Example: 2026-07-28. - `sort_by` (`string`, required): Metric to sort the top pins by. Valid values: ENGAGEMENT, SAVE, IMPRESSION, OUTBOUND_CLICK, PIN_CLICK. One of: `ENGAGEMENT`, `SAVE`, `IMPRESSION`, `OUTBOUND_CLICK`, `PIN_CLICK`. - `start_date` (`string`, required): Start date of the metric report window (UTC), inclusive. Format: YYYY-MM-DD. Cannot be more than 90 days before today. Example: 2026-07-01. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this request, instead of the token user's own account. Only needed when using Pinterest Business Access to view or report on data owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `app_types` (`string`, optional): Apps or devices to get data for, default is all. Valid values: ALL, MOBILE, TABLET, WEB. Defaults to ALL. One of: `ALL`, `MOBILE`, `TABLET`, `WEB`. Default: `ALL`. - `content_type` (`string`, optional): Filter to paid or organic data. Default is all. Valid values: ALL, PAID, ORGANIC. Defaults to ALL. One of: `ALL`, `PAID`, `ORGANIC`. Default: `ALL`. - `created_in_last_n_days` (`integer`, optional): Limit results to pins created in the last "n" days. The only value the Pinterest API currently accepts is 30. Leave blank to apply no creation-date filter. One of: `30`. - `from_claimed_content` (`string`, optional): Filter on Pins that match your claimed domain. Valid values: OTHER, CLAIMED, BOTH. Defaults to BOTH. One of: `OTHER`, `CLAIMED`, `BOTH`. Default: `BOTH`. - `metric_types` (`array`, optional): Metric types to get data for. Valid values: ENGAGEMENT, ENGAGEMENT_RATE, IMPRESSION, OUTBOUND_CLICK, OUTBOUND_CLICK_RATE, PIN_CLICK, PIN_CLICK_RATE, SAVE, SAVE_RATE. Defaults to all metric types when omitted. Example: ["IMPRESSION", "SAVE"]. - `num_of_pins` (`integer`, optional): Number of top pins to include in the response. Defaults to 10. Maximum is 50, minimum is 1. Default: `10`. - `pin_format` (`string`, optional): Pin formats to get data for, default is all. Valid values: ALL, ORGANIC_IMAGE, ORGANIC_PRODUCT, ORGANIC_VIDEO, ADS_STANDARD, ADS_PRODUCT, ADS_VIDEO, ADS_IDEA. Defaults to ALL. One of: `ALL`, `ORGANIC_IMAGE`, `ORGANIC_PRODUCT`, `ORGANIC_VIDEO`, `ADS_STANDARD`, `ADS_PRODUCT`, `ADS_VIDEO`, `ADS_IDEA`. Default: `ALL`. - `source` (`string`, optional): Filter to activity from Pins created and saved by you, or activity created and saved by others from your claimed accounts. Default is all. Valid values: ALL, YOUR_PINS, OTHER_PINS. Defaults to ALL. One of: `ALL`, `YOUR_PINS`, `OTHER_PINS`. Default: `ALL`. Example input: `{"end_date":"","sort_by":"ENGAGEMENT","start_date":""}` ### `pinterest_user_account_top_video_pins_list` List Top Video Pins Analytics · Read-only List the connected Pinterest user account's top-performing video Pins (up to the top 50) over a date range, ranked by a chosen video metric. Returns per-metric data status plus, for each returned video Pin, its Pin ID and a map of the requested video metric values (e.g. VIDEO_MRC_VIEW, VIDEO_AVG_WATCH_TIME, VIDEO_10S_VIEW). Use this to see which video Pins are driving the most views and watch time. Use pinterest_user_account_top_pins_list instead for a metric set spanning all Pin formats, not just video. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `end_date` (`string`, required): End date of the metric report window (UTC), inclusive. Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. Example: 2026-07-28. - `sort_by` (`string`, required): Metric to sort the top video pins by. Valid values: SAVE, IMPRESSION, OUTBOUND_CLICK, VIDEO_MRC_VIEW, VIDEO_AVG_WATCH_TIME, VIDEO_V50_WATCH_TIME, QUARTILE_95_PERCENT_VIEW, VIDEO_10S_VIEW, VIDEO_START. One of: `SAVE`, `IMPRESSION`, `OUTBOUND_CLICK`, `VIDEO_MRC_VIEW`, `VIDEO_AVG_WATCH_TIME`, `VIDEO_V50_WATCH_TIME`, `QUARTILE_95_PERCENT_VIEW`, `VIDEO_10S_VIEW`, `VIDEO_START`. - `start_date` (`string`, required): Start date of the metric report window (UTC), inclusive. Format: YYYY-MM-DD. Cannot be more than 90 days before today. Example: 2026-07-01. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this request, instead of the token user's own account. Only needed when using Pinterest Business Access to view or report on data owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `app_types` (`string`, optional): Apps or devices to get data for, default is all. Valid values: ALL, MOBILE, TABLET, WEB. Defaults to ALL. One of: `ALL`, `MOBILE`, `TABLET`, `WEB`. Default: `ALL`. - `content_type` (`string`, optional): Filter to paid or organic data. Default is all. Valid values: ALL, PAID, ORGANIC. Defaults to ALL. One of: `ALL`, `PAID`, `ORGANIC`. Default: `ALL`. - `created_in_last_n_days` (`integer`, optional): Limit results to pins created in the last "n" days. The only value the Pinterest API currently accepts is 30. Leave blank to apply no creation-date filter. One of: `30`. - `from_claimed_content` (`string`, optional): Filter on Pins that match your claimed domain. Valid values: OTHER, CLAIMED, BOTH. Defaults to BOTH. One of: `OTHER`, `CLAIMED`, `BOTH`. Default: `BOTH`. - `metric_types` (`array`, optional): Metric types to get data for. Valid values: IMPRESSION, SAVE, VIDEO_MRC_VIEW, VIDEO_AVG_WATCH_TIME, VIDEO_V50_WATCH_TIME, QUARTILE_95_PERCENT_VIEW, VIDEO_10S_VIEW, VIDEO_START, OUTBOUND_CLICK. Defaults to all metric types when omitted. Example: ["IMPRESSION", "SAVE"]. - `num_of_pins` (`integer`, optional): Number of top pins to include in the response. Defaults to 10. Maximum is 50, minimum is 1. Default: `10`. - `pin_format` (`string`, optional): Pin formats to get data for, default is all. Valid values: ALL, ORGANIC_IMAGE, ORGANIC_PRODUCT, ORGANIC_VIDEO, ADS_STANDARD, ADS_PRODUCT, ADS_VIDEO, ADS_IDEA. Defaults to ALL. One of: `ALL`, `ORGANIC_IMAGE`, `ORGANIC_PRODUCT`, `ORGANIC_VIDEO`, `ADS_STANDARD`, `ADS_PRODUCT`, `ADS_VIDEO`, `ADS_IDEA`. Default: `ALL`. - `source` (`string`, optional): Filter to activity from Pins created and saved by you, or activity created and saved by others from your claimed accounts. Default is all. Valid values: ALL, YOUR_PINS, OTHER_PINS. Defaults to ALL. One of: `ALL`, `YOUR_PINS`, `OTHER_PINS`. Default: `ALL`. Example input: `{"end_date":"","sort_by":"SAVE","start_date":""}` ### `pinterest_user_account_website_verification_code_get` Get Website Verification Code · Read-only Get the verification proof to install on a website before claiming it on the authenticated Pinterest account. Returns a metatag, an HTML file (filename and file_content), a DNS TXT record, and the raw verification_code -- any one of which proves ownership. Use this before the verify-website tool: place the matching proof (metatag, HTML file, or DNS TXT record) on the site first, then call verify-website with the corresponding verification_method. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this lookup, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{}` ### `pinterest_user_account_websites_list` List Account Websites · Read-only List the websites associated with the authenticated Pinterest account, claimed or not. Returns a page of website objects (website URL, verification status, and verified_at timestamp) plus a bookmark token for the next page. Use this to check which websites are claimed. Use the verify-website tool to claim a new one, or the unverify-website tool to remove an existing claim. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `bookmark` (`string`, optional): Cursor token from a previous response's bookmark field, used to fetch the next page of websites. Omit or leave blank to start from the first page. - `page_size` (`integer`, optional): Maximum number of websites to return in a single page. Integer between 1 and 250. Defaults to 25. Default: `25`. Example input: `{}` ### `pinterest_user_followed_interests_list` List Followed Interests · Read-only List the interests a Pinterest user follows. Returns a page of interest objects plus a bookmark token for the next page. Use this to see which topics a specific user follows by username. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `username` (`string`, required): The username of the Pinterest user whose followed interests to list. Must be a valid username (not a numeric ID). Example: designlovers. - `bookmark` (`string`, optional): Cursor token from a previous response's bookmark field, used to fetch the next page of interests. Omit or leave blank to start from the first page. - `page_size` (`integer`, optional): Maximum number of interests to return in a single page. Integer between 1 and 250. Defaults to 25. Default: `25`. Example input: `{"username":""}` ### `pinterest_board_create` Create Board · Write Create a new board on the authenticated Pinterest account, or on a Business Access ad account you manage. Returns the created board's full details: id, name, description, privacy setting, and creation metadata. Use this to make a new board before adding Pins or sections to it. Use pinterest_board_update to change an existing board instead. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `name` (`string`, required): Name of the board to create. Example: Summer recipes. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this creation, instead of the token user's own account. Only needed when using Pinterest Business Access to create a board owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `description` (`string`, optional): Description of the board's purpose or content. Plain text, shown to board visitors. Example: My favorite summer recipes. - `is_ads_only` (`boolean`, optional): If true, the board is created as ad-only and can store ad-only Pins. When set, the board's name automatically becomes "Ad-only Pins" and its privacy is forced to PROTECTED, overriding the name and privacy fields. Defaults to false. Default: `false`. - `privacy` (`string`, optional): Privacy setting for the board. PUBLIC boards are visible to everyone; PROTECTED boards are visible only to people you approve; SECRET boards are visible only to you and collaborators. Defaults to PUBLIC. One of: `PUBLIC`, `PROTECTED`, `SECRET`. Default: `PUBLIC`. Example input: `{"name":""}` ### `pinterest_board_section_create` Create Board Section · Write Create a new section on a board owned by the authenticated Pinterest account, or on a group board shared with that account. Returns the created section's id and name. Use this to add a sub-collection to an existing board before assigning Pins to it. Use pinterest_board_section_update instead to rename a section that already exists. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board to create the section on. Digits only. Example: 549755885175. - `name` (`string`, required): Name of the section to create. Between 1 and 180 characters. Example: Salads. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this creation, instead of the token user's own account. Only needed when using Pinterest Business Access to create a section on a board owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"board_id":"","name":""}` ### `pinterest_board_section_update` Update Board Section · Write Rename an existing section on a board owned by the authenticated Pinterest account, or on a group board shared with that account. Returns the updated section object. Use this to change a section's name. Use pinterest_board_section_create instead to add a new section to a board. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board that owns the section. Digits only. Example: 549755885175. - `name` (`string`, required): New name for the section. Between 1 and 180 characters, required by this endpoint even though it is the only field being changed. Example: Salads. - `section_id` (`string`, required): The unique numeric identifier of the board section to update. Digits only. Example: 907186624124. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this update, instead of the token user's own account. Only needed when using Pinterest Business Access to update a section on a board owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"board_id":"","name":"","section_id":""}` ### `pinterest_board_update` Update Board · Write Update the name, description, or privacy setting of an existing board owned by the authenticated Pinterest account, or on a Business Access ad account you manage. Returns the updated board's full details. Use this to rename a board, edit its description, or switch it between public and secret. Use pinterest_board_create to make a new board instead. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board to update. Digits only. Example: 549755885175. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this update, instead of the token user's own account. Only needed when using Pinterest Business Access to update a board owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `description` (`string`, optional): New description for the board. Plain text, shown to board visitors. Omit to leave the description unchanged. Example: My favorite summer recipes. - `name` (`string`, optional): New name for the board. Omit to leave the name unchanged. Example: Summer recipes. - `privacy` (`string`, optional): New privacy setting for the board. PUBLIC boards are visible to everyone; SECRET boards are visible only to you and collaborators. Omit to leave privacy unchanged. One of: `PUBLIC`, `SECRET`. Example input: `{"board_id":""}` ### `pinterest_catalog_create` Create Catalog · Write Create a new Pinterest catalog owned by the authenticated account, or by a Business Access ad account you manage. Returns the created catalog's id, name, catalog_type, and creation/update timestamps. Use this before creating catalog feeds, which must attach to an existing catalog_id. Use catalogs_list to check for an existing catalog before creating a duplicate. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `catalog_type` (`string`, required): Type of catalog to create. One of RETAIL (physical products), HOTEL, or CREATIVE_ASSETS. Access to CREATIVE_ASSETS is restricted to a specific group of users; contact your Pinterest partner manager if you need it. One of: `RETAIL`, `HOTEL`, `CREATIVE_ASSETS`. - `name` (`string`, required): A human-friendly name for the new catalog. Shown in the Pinterest catalogs UI. Example: Spring 2026 Retail Catalog. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this catalog, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"catalog_type":"RETAIL","name":""}` ### `pinterest_catalog_feed_create` Create Catalog Feed · Write Create a new Pinterest catalog feed that Pinterest will download and process from a hosted file URL, for a RETAIL, HOTEL, or CREATIVE_ASSETS catalog. Returns the created feed's id, name, format, location, status, and catalog_type. Use this to register a product, hotel, or creative-assets data feed for ingestion. RETAIL and CREATIVE_ASSETS feeds require default_country and default_locale; HOTEL feeds must omit default_country and default_availability. Use catalogs_list or catalog_create first if you don't have a catalog_id. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `catalog_type` (`string`, required): Type of catalog this feed belongs to. Determines which optional fields apply: RETAIL and CREATIVE_ASSETS require default_country; HOTEL rejects default_country and default_availability entirely. One of: `RETAIL`, `HOTEL`, `CREATIVE_ASSETS`. - `default_locale` (`string`, required): Locale used within the feed file for product descriptions. Required for all catalog types. Example: en-US. One of: `af-ZA`, `ar-SA`, `bg-BG`, `bn-IN`, `cs-CZ`, `da-DK`, `de`, `el-GR`, `en-AU`, `en-CA`, `en-GB`, `en-IN`, `en-US`, `es-419`, `es-AR`, `es-ES`, `es-MX`, `fi-FI`, `fr`, `fr-CA`, `he-IL`, `hi-IN`, `hr-HR`, `hu-HU`, `id-ID`, `it`, `ja`, `ko-KR`, `ms-MY`, `nb-NO`, `nl`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `sv-SE`, `te-IN`, `th-TH`, `tl-PH`, `tr`, `uk-UA`, `vi-VN`, `zh-CN`, `zh-TW`. - `format` (`string`, required): The file format of the feed. One of TSV, CSV, XML, or INTEGRATION. One of: `TSV`, `CSV`, `XML`, `INTEGRATION`. - `location` (`string`, required): The URL where the feed file is available for download; Pinterest fetches from this URL to process the feed. Must begin with http://, https://, ftp://, or sftp://. Example: https://example.com/feeds/products.csv. - `name` (`string`, required): A human-friendly name for the new feed. Shown in the Pinterest catalogs UI. Example: Spring 2026 Product Feed. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this feed, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `catalog_id` (`string`, optional): Unique identifier of the catalog this feed belongs to. If not provided, the feed uses a default catalog based on catalog_type. Digits only. Example: 864344156814050986. - `credentials` (`object`, optional): HTTP basic-auth credentials for downloading the feed file, only needed when the location URL requires a username and password. Both fields are required together when provided. Example: {"username": "feed-user", "password": "feed-pass"}. - `default_availability` (`string`, optional): Default product availability applied to items in this feed that don't specify their own. Only accepted for RETAIL catalogs; omit for HOTEL and CREATIVE_ASSETS. One of IN_STOCK, OUT_OF_STOCK, or PREORDER. One of: `IN_STOCK`, `OUT_OF_STOCK`, `PREORDER`. - `default_country` (`string`, optional): ISO 3166-1 alpha-2 country code used for items in this feed that don't specify their own. Required for RETAIL and CREATIVE_ASSETS catalog types; must be left blank for HOTEL, which rejects this field entirely. Example: US. - `default_currency` (`string`, optional): ISO 4217 three-letter currency code used for items in this feed that don't specify their own price currency. Example: USD. - `preferred_processing_schedule` (`object`, optional): Daily processing schedule for this feed. Shape: {"time": "HH:MM", "timezone": ""}. If omitted, Pinterest processes the feed at a random time each day. - `status` (`string`, optional): Initial status of the feed. One of ACTIVE or INACTIVE. Defaults to ACTIVE. One of: `ACTIVE`, `INACTIVE`. Default: `ACTIVE`. Example input: `{"catalog_type":"RETAIL","default_locale":"af-ZA","format":"TSV","location":"","name":""}` ### `pinterest_catalog_feed_ingest` Ingest Catalog Feed · Write Trigger Pinterest to start downloading and processing a catalog feed's items immediately, instead of waiting for its next scheduled run. Returns the new ingestion record's id, status, and created_at timestamp for the run that was just started. Use this after creating or updating a feed when you want it processed right away. Use catalog_feed_processing_results_list afterward to check the run's progress and outcome. Restricted to accounts with partner access; contact your Pinterest partner manager if you get a permissions error. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `feed_id` (`string`, required): The unique numeric identifier of the catalog feed to ingest. Digits only. Example: 864344156814050986. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this ingestion, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"feed_id":""}` ### `pinterest_catalog_feed_update` Update Catalog Feed · Write Update an existing Pinterest catalog feed's name, format, location, credentials, default currency, default availability, processing schedule, or status. Returns the updated feed object with its new field values. Use this to change a feed's source file, credentials, or pause/reactivate it via status. Use catalog_feed_get first to see current values, and catalog_feeds_list to find the feed_id. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_type` (`string`, required): Catalog type this feed belongs to. Must match the feed's existing catalog_type (from catalog_feed_get). Determines which optional fields are accepted: only RETAIL accepts default_availability. One of: `RETAIL`, `HOTEL`, `CREATIVE_ASSETS`. - `feed_id` (`string`, required): The unique numeric identifier of the catalog feed to update. Digits only. Example: 864344156814050986. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this update, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an Owner, Admin, or Catalogs Manager role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `credentials` (`object`, optional): HTTP basic-auth credentials for downloading the feed file, only needed when the location URL requires a username and password. Both fields are required together when provided. Example: {"username": "feed-user", "password": "feed-pass"}. - `default_availability` (`string`, optional): Default product availability applied to items in this feed that don't specify their own. Only accepted when catalog_type is RETAIL; leave blank for HOTEL and CREATIVE_ASSETS. One of IN_STOCK, OUT_OF_STOCK, or PREORDER. One of: `IN_STOCK`, `OUT_OF_STOCK`, `PREORDER`. - `default_currency` (`string`, optional): ISO 4217 three-letter currency code used for items in this feed that don't specify their own price currency. Example: USD. - `format` (`string`, optional): The file format of the feed. One of TSV, CSV, XML, or INTEGRATION. One of: `TSV`, `CSV`, `XML`, `INTEGRATION`. - `location` (`string`, optional): The URL where the feed file is available for download; Pinterest fetches from this URL to process the feed. Must begin with http://, https://, ftp://, or sftp://. Example: https://example.com/feeds/products.csv. - `name` (`string`, optional): A human-friendly name for the feed. Shown in the Pinterest catalogs UI. Example: Spring 2026 Product Feed. - `preferred_processing_schedule` (`object`, optional): Daily processing schedule for this feed. Shape: {"time": "HH:MM", "timezone": ""}. If omitted, existing schedule is left unchanged. - `status` (`string`, optional): Status to set on the feed. One of ACTIVE or INACTIVE. Omit to leave the current status unchanged. One of: `ACTIVE`, `INACTIVE`. Example input: `{"catalog_type":"RETAIL","feed_id":""}` ### `pinterest_catalog_local_stores_create` Batch Create Local Stores · Write Create one or more local, brick-and-mortar stores in bulk for a Pinterest catalog. Returns an array with one result per store, each either the created store record or an error for that entry. Use pinterest_catalog_local_stores_update to modify existing stores and pinterest_catalog_local_stores_list to look them up. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `catalog_id` (`string`, required): Unique identifier of the catalog to create local stores in. Digits only, up to 19 characters. - `stores` (`string`, required): JSON array of local stores to create. Each item: {"store_code": "store_1" (required, unique per catalog), "name": "Sunnyvale Store" (required), "country": "US" (required, ISO 3166-1 alpha-2), "address_primary": "123 Johnson St", "address_secondary": "Suite 100", "city": "Sunnyvale", "region": "CA", "postal_code": "94043", "latitude": -30.21, "longitude": 50.45}. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this write, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"catalog_id":"","stores":""}` ### `pinterest_catalog_local_stores_update` Batch Update Local Stores · Write Update one or more local stores in bulk for a Pinterest catalog. Each update object must include the store's id plus any fields to change. Returns an array with one result per requested update, each either the updated store record or an error for that entry. Use pinterest_catalog_local_stores_list to find store IDs first. Use pinterest_catalog_local_stores_create to add new stores instead. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_id` (`string`, required): Unique identifier of the catalog whose local stores you want to update. Digits only, up to 19 characters. - `stores` (`string`, required): JSON array of local store updates. Each item must include "id" (the local store's ID) plus any fields to change: store_code, name, country, address_primary, address_secondary, city, region, postal_code, latitude, longitude. Fields omitted from an item are left unchanged. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this write, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"catalog_id":"","stores":""}` ### `pinterest_catalog_product_group_create` Create Catalog Product Group · Write Create a new catalog product group in a Pinterest Catalogs feed or catalog, scoped by a filters object that selects which items belong to it. Supports a feed-based group (feed_id) or a catalog/vertical-based group for RETAIL, HOTEL, or CREATIVE_ASSETS catalogs (catalog_id + catalog_type). Returns the created product group's ID, name, catalog association, and filter configuration. Use this to define a reusable, rule-based collection of catalog items for ad targeting or reporting. Use pinterest_catalog_products_by_filter_list first to preview which products a filter set would match before creating the group. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `filters` (`object`, required): Object holding the filter criteria that select which catalog items belong to this product group. Shape: {"any_of": []} to match items satisfying ANY listed criterion, or {"all_of": []} to require ALL of them. Each filter key object has one key (e.g. ITEM_ID, MIN_PRICE, BRAND, AVAILABILITY, CUSTOM_LABEL_0) whose value is a criteria object, typically {"values": [...]} and optionally {"negated": true}. Cannot be empty. Example: {"any_of": [{"ITEM_ID": {"values": ["123456789"]}}]}. - `name` (`string`, required): Name of the catalog product group. Shown in the Pinterest Catalogs UI and used to reference the group elsewhere (e.g. ad group targeting). Example: Most Popular. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this create, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `catalog_id` (`string`, optional): Catalog ID the product group belongs to. Required, together with catalog_type, when creating a catalog/vertical-based product group (RETAIL, HOTEL, or CREATIVE_ASSETS) instead of a feed-based one. Numeric string. Example: 2680059592705. - `catalog_type` (`string`, optional): Selects a catalog/vertical-based product group instead of a feed-based one. When set, catalog_id and filters (in the catalog-specific shape) are required; feed_id must be omitted. RETAIL catalog-based groups are only available to selected partners. Valid values: RETAIL, HOTEL, CREATIVE_ASSETS. Omit entirely to create a feed-based group with feed_id instead. One of: `RETAIL`, `HOTEL`, `CREATIVE_ASSETS`. - `country` (`string`, optional): ISO 3166-1 alpha-2 country code to scope the product group to, for RETAIL catalog-based groups only. Two-letter code. Example: US. - `description` (`string`, optional): Free-text description of the product group. - `feed_id` (`string`, optional): Catalog Feed ID the product group belongs to. Required when creating a feed-based product group, i.e. when catalog_type is omitted. Must be omitted when catalog_type is set. Numeric string. Example: 2680059592705. - `locale` (`string`, optional): Locale to scope the product group to, for RETAIL catalog-based groups only. Format: language-COUNTRY or language. Example: en-US. Example input: `{"filters":{},"name":""}` ### `pinterest_catalog_product_group_update` Update Catalog Product Group · Write Update an existing catalog product group's name, description, filters, or (for catalog/vertical-based groups) catalog_type, country, and locale. Only the fields you provide are changed; omitted fields keep their current value. Returns the updated product group's ID, name, and filter configuration. Use this to adjust which catalog items a product group matches without deleting and recreating it. Requires the product group's ID from pinterest_catalog_product_group_create or pinterest_catalog_product_groups_list. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `product_group_id` (`string`, required): The unique numeric identifier of the catalog product group to update. Digits only. Example: 2680059592705. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this update, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `catalog_type` (`string`, optional): For catalog/vertical-based product groups only: RETAIL, HOTEL, or CREATIVE_ASSETS. Must match the group's existing catalog type; omit for feed-based groups. Leave unset if you are not changing catalog-specific fields. One of: `RETAIL`, `HOTEL`, `CREATIVE_ASSETS`. - `country` (`string`, optional): ISO 3166-1 alpha-2 country code to update the product group to, for RETAIL catalog-based groups only. Two-letter code. Example: US. - `description` (`string`, optional): New free-text description of the product group. - `filters` (`object`, optional): New filter criteria selecting which catalog items belong to this product group; replaces the existing filters entirely. Shape: {"any_of": []} to match items satisfying ANY listed criterion, or {"all_of": []} to require ALL of them. Example: {"any_of": [{"ITEM_ID": {"values": ["123456789"]}}]}. - `locale` (`string`, optional): Locale to update the product group to, for RETAIL catalog-based groups only. Format: language-COUNTRY or language. Example: en-US. - `name` (`string`, optional): New name for the catalog product group. Example input: `{"product_group_id":""}` ### `pinterest_catalog_report_create` Create Catalog Report · Write Start an asynchronous build of a catalogs report for a RETAIL or HOTEL catalog you own: feed ingestion issues, distribution issues, or (RETAIL only) an all-items export. Repeating the same request with identical parameters on the same day returns the same report even if the underlying data has changed since. The All Items report is limited to 25 million items per catalog. Returns a token identifying the report being built. Use this to kick off a new report, then pass the returned token to pinterest_catalog_report_get to fetch a download URL once the report is ready. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `catalog_type` (`string`, required): Type of catalog the report is being built for. Determines which report_type values are available in the report object: RETAIL supports FEED_INGESTION_ISSUES, DISTRIBUTION_ISSUES, and ALL_ITEMS; HOTEL supports FEED_INGESTION_ISSUES and DISTRIBUTION_ISSUES. One of: `RETAIL`, `HOTEL`. - `report` (`object`, required): Object describing which report to build. Always include "report_type": one of FEED_INGESTION_ISSUES (requires feed_id, optional processing_result_id), DISTRIBUTION_ISSUES, or ALL_ITEMS (RETAIL only; optional catalog_id and product_group_id to scope the export). Example: {"report_type": "FEED_INGESTION_ISSUES", "feed_id": "2680059592705"}. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this report, instead of the token user's own account. Only needed when using Pinterest Business Access; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"catalog_type":"RETAIL","report":{"report_type":"FEED_INGESTION_ISSUES","feed_id":"2680059592705"}}` ### `pinterest_media_create` Register Media Upload · Write Register a new video media upload with Pinterest, obtaining an upload URL and the parameters needed to upload the file bytes separately. Returns media_id, media_type, upload_url, and upload_parameters (the multipart form fields required for the follow-up file upload request). Use this as the first step before creating a video Pin. This tool only registers the upload -- it does not upload the video file itself; you must separately POST the video (multipart/form-data, using upload_parameters plus your file) to upload_url outside of this tool, then call pinterest_media_get to check the resulting media_id's processing status before referencing it when creating a Pin. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `media_type` (`string`, required): The type of media being registered for upload. Currently Pinterest's media registration endpoint only supports 'video'; images are attached to a Pin directly via a URL or base64 string when creating the Pin, not through this endpoint. Example: video. One of: `video`. Example input: `{"media_type":"video"}` ### `pinterest_pin_create` Create Pin · Write Create an image Pin on a board (or board section) owned by the authenticated Pinterest account, or on a Business Access ad account you manage. Returns the created Pin's full details: id, title, description, link, media, board ID, and creation metadata. Use this to publish a new image Pin from a publicly reachable image URL. For video, carousel, or multi-image Pins, first register the media with pinterest_media_create to obtain a media_id, then build the request outside this tool -- this tool only covers the single-image-URL case. Use pinterest_pin_update to change an existing Pin instead. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board this Pin will be created on. Digits only. Example: 549755885175. - `media_source_url` (`string`, required): Publicly accessible URL of the image to use as the Pin's media. Must be reachable by Pinterest's servers at request time. Example: https://example.com/images/strawberries.jpg. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this creation, instead of the token user's own account. Only needed when using Pinterest Business Access to create a Pin owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `alt_text` (`string`, optional): Accessible alternative text describing the Pin's image, shown to screen readers. Plain text, up to 500 characters. Example: A bowl of fresh strawberries on a wooden table. - `board_section_id` (`string`, optional): The unique numeric identifier of the board section this Pin will be created in. Digits only. Omit to create the Pin directly on the board with no section. Example: 549755885176. - `description` (`string`, optional): Description of the Pin's content, shown to viewers. Plain text, up to 800 characters. Example: A quick and easy summer dessert recipe. - `link` (`string`, optional): Destination URL that viewers reach by clicking through the Pin. Up to 2048 characters. Example: https://example.com/recipes/summer-dessert. - `title` (`string`, optional): Title of the Pin, shown to viewers above the description. Plain text, up to 100 characters. Example: Summer Strawberry Dessert. Example input: `{"board_id":"","media_source_url":""}` ### `pinterest_pin_product_tags_add` Add Product Tags to Pin · Write Add one or more product tags to a hero Pin, tagging existing product Pins onto it. Returns the hero Pin's full current list of product tags. Use this to tag product Pins onto a hero Pin for shoppable content. A product tag already present on the Pin is treated as a no-op success; if any tag fails eligibility, the whole request fails. Use pinterest_pin_product_tags_list to see a Pin's current tags, or pinterest_pin_product_tags_delete to remove tags instead. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `pin_id` (`string`, required): The unique numeric identifier of the hero Pin that will receive the product tags. Digits only. Example: 526931230485217455. - `product_pin_ids` (`array`, required): Array of Pin IDs for the product Pins to tag onto the hero Pin. Up to 24 items. Duplicate IDs in the same request will result in an error. Example: ["526931230485217455", "526931230485217456"]. Example input: `{"pin_id":"","product_pin_ids":["526931230485217455","526931230485217456"]}` ### `pinterest_pin_save` Save Pin · Write Save (repin) any public Pin -- including one you don't own -- to a board or board section owned by the authenticated Pinterest account, or by a Business Access ad account you manage. Returns the newly created Pin object created by the save. Use this to repin existing content (image, video, Idea, or product Pins) onto one of your own boards. Use pinterest_pin_create instead when publishing brand-new content you created yourself. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `board_id` (`string`, required): The unique numeric identifier of the board to save this Pin to. Digits only. Example: 549755885175. - `pin_id` (`string`, required): The unique numeric identifier of the (public) Pin to save. Digits only. Example: 526931230485217455. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this save, instead of the token user's own account. Only needed when using Pinterest Business Access to save a Pin as another user you manage; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `board_section_id` (`string`, optional): The unique numeric identifier of the board section to save this Pin into. Digits only. Omit to save it directly on the board with no section. Example: 549755885176. Example input: `{"board_id":"","pin_id":""}` ### `pinterest_pin_update` Update Pin · Write Update the title, description, link, alt text, or board placement of an existing Pin owned by the authenticated Pinterest account, or on a Business Access ad account you manage. Returns the updated Pin's full details. Use this to edit a Pin's metadata or move it to a different board or board section. This tool does not edit carousel slot content. Use pinterest_pin_create to make a new Pin instead. This endpoint is currently in beta and not available to all Pinterest apps. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `pin_id` (`string`, required): The unique numeric identifier of the Pin to update. Digits only. Example: 526931230485217455. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this update, instead of the token user's own account. Only needed when using Pinterest Business Access to update a Pin owned by that ad account's user; the token user must hold an appropriate Business Access role on the ad account. Numeric string, up to 18 digits. Example: 549755885175. - `alt_text` (`string`, optional): New accessible alternative text describing the Pin's image, shown to screen readers. Plain text, up to 500 characters. Omit to leave the alt text unchanged. Example: A bowl of fresh strawberries on a wooden table. - `board_id` (`string`, optional): New board this Pin should belong to. Digits only. Omit to leave the Pin on its current board. Example: 549755885175. - `board_section_id` (`string`, optional): New board section this Pin should belong to. Digits only. Omit to leave the Pin's section unchanged. Example: 549755885176. - `description` (`string`, optional): New description for the Pin. Plain text, up to 800 characters. Omit to leave the description unchanged. Example: A quick and easy summer dessert recipe. - `link` (`string`, optional): New destination URL viewers reach by clicking through the Pin. Up to 2048 characters. Omit to leave the link unchanged. Example: https://example.com/recipes/summer-dessert. - `title` (`string`, optional): New title for the Pin. Plain text, up to 100 characters. Omit to leave the title unchanged. Example: Summer Strawberry Dessert. Example input: `{"pin_id":""}` ### `pinterest_user_follow` Follow User · Write Follow another Pinterest user as the authenticated account. Returns the followed user's type and username. Use this to start following a specific user by username. This endpoint is currently in beta and may not be available to all apps. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `username` (`string`, required): The username of the Pinterest user to follow. Must be a valid username (not a numeric ID). Example: designlovers. - `auto_follow` (`boolean`, optional): Whether this follow request is the result of an auto-follow link click (e.g., a partner site or email follow link), rather than a direct in-app follow. Only selected partners can be auto-followed this way; Pinterest verifies eligibility. Defaults to false. Default: `false`. Example input: `{"username":""}` ### `pinterest_catalog_items_batch_create` Batch Create/Update/Delete Catalog Items · Destructive Create, update, upsert, or delete catalog items in bulk for a Pinterest product catalog, up to 1000 items per request. Returns the batch record with a batch_id and status — processing happens asynchronously, so poll pinterest_catalog_items_batch_get for the final per-item results. Use the operation field to choose CREATE, UPDATE, UPSERT, DELETE, or DELETE_DISCONTINUED. Use pinterest_catalog_items_list instead to just look up existing items. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `country` (`string`, required): ISO 3166-1 alpha-2 country code for the items in this batch. Example: US. - `items` (`string`, required): JSON array of up to 1000 item records, shaped according to the chosen operation. CREATE/UPSERT items: {"item_id": "DS0294-M", "attributes": {"title": "...", "description": "...", "link": "...", "image_link": "...", "price": "19.99 USD", "availability": "in stock", ...}}. UPDATE items: {"item_id": "DS0294-M", "attributes": {"price": "24.99 USD"}, "update_mask": ["price"]} (fields named in update_mask but not present under attributes are cleared). DELETE and DELETE_DISCONTINUED items: {"item_id": "DS0294-M"}. - `language` (`string`, required): Language/locale for the items in this batch, as a BCP-47 or Pinterest CatalogsLocale code. Example: en-US. - `operation` (`string`, required): The batch operation to perform on every item in this request: CREATE, UPDATE, UPSERT, DELETE, or DELETE_DISCONTINUED. One of: `CREATE`, `UPDATE`, `UPSERT`, `DELETE`, `DELETE_DISCONTINUED`. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this write, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"country":"","items":"","language":"","operation":"CREATE"}` ### `pinterest_catalog_local_inventory_items_batch_create` Batch Create/Update/Delete Local Inventory Items · Destructive Create, update, upsert, or delete local inventory items — store-specific stock and price overrides — in bulk for a Pinterest catalog, up to 1000 operations per request. Returns either a batch record or a per-operation result array, depending on how Pinterest processes the request; poll pinterest_catalog_supplemental_items_batch_get for the final status if a batch_id comes back. Use pinterest_catalog_local_inventory_items_list instead to look up existing records. Every operation must include both item_id and store_code. Read only: no. Destructive: yes. Idempotent (safe to retry): no. Inputs: - `catalog_id` (`string`, required): Unique identifier of the catalog to write local inventory items in. Digits only, up to 19 characters. - `operations` (`string`, required): JSON array of up to 1000 local inventory operations. Each item selects its own operation type: {"operation": "CREATE"|"UPDATE"|"UPSERT"|"DELETE", "item_id": "item_id_1", "store_code": "store_1", "attributes": {"availability": "in stock", "price": "19.99 USD", ...}}. attributes is required for CREATE, UPDATE, and UPSERT operations, and omitted for DELETE. - `ad_account_id` (`string`, optional): Unique identifier of a Business Access ad account to use as the operating account for this write, instead of the token user's own account. Numeric string, up to 18 digits. Example: 549755885175. Example input: `{"catalog_id":"","operations":""}` ### `pinterest_pin_product_tags_delete` Delete Pin Product Tags · Destructive Permanently remove one or more product tags from a hero Pin. Returns no content on success. A product tag that isn't currently on the Pin is treated as a no-op success rather than an error. Use this to untag product Pins from a hero Pin. Use pinterest_pin_product_tags_list first to see the Pin's current tags, or pinterest_pin_product_tags_add to add tags instead. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `pin_id` (`string`, required): The unique numeric identifier of the hero Pin to remove product tags from. Digits only. Example: 526931230485217455. - `product_pin_ids` (`array`, required): Array of Pin IDs identifying the product tags to remove from the hero Pin. Up to 24 items. Example: ["526931230485217455", "526931230485217456"]. Example input: `{"pin_id":"","product_pin_ids":["526931230485217455","526931230485217456"]}` ## Related Other Media connectors ([all 31](/agentkit/connectors/?category=media)): - [Reddit](/agentkit/connectors/reddit/): Scalekit connector, OAuth, 105 tools - [Diarize](/agentkit/connectors/diarize/): Scalekit connector, Access token, 3 tools - [YouTube](/agentkit/connectors/youtube/): Scalekit connector, OAuth, 45 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |