📌 Pinterest Content Scheduler — List Boards, Read Pins & Create/Schedule Pins via Pinterest API v5

🔗 View on Apify Store | 🇺🇸 English | 🇧🇷 Português

Manage your Pinterest content through the official Pinterest API v5. List your boards, read the pins inside a board, and create (publish) new pins from a public image URL — all with a single OAuth2 access token. Bring your own token (BYOC), pick a mode, and the actor returns clean, structured records ready for your pipeline.

✨ Features

• 📋 List boards — Retrieve your Pinterest boards with name, description, pin count, follower count, privacy, and owner
• 🖼️ Read board pins — List pins inside a specific board with title, description, link, and original media URL
• ➕ Create pins — Publish a new pin to a board from a public image URL, with title, description, and destination link
• 🔑 Official API v5 — Talks directly to api.pinterest.com/v5 (no scraping, no browser)
• 🔒 Bring Your Own Credentials — Uses your own Pinterest OAuth2 access token (stored as a secret input)
• 📄 Automatic pagination — Cursor (bookmark) based paging across boards and pins up to your maxItems limit
• 🛟 Self-diagnosing guards — If the token is missing or the query returns zero items, the actor writes a setup/diagnostic guide to the dataset instead of failing silently
• ⏱️ Clear error mapping — Friendly messages for 401 (invalid token), 403 (missing scopes), 404, and 429 (rate limit)

📥 Input

Parameter	Type	Required	Default	Description
mode	string (enum)	✅	"list-boards"	Operation: list-boards, get-user-pins, or create-pin
accessToken	string (secret)	✅	—	Pinterest OAuth2 access token from developers.pinterest.com (needs boards:read and/or pins:write scopes)
boardId	string	⚠️	—	Target board ID. Required for get-user-pins and create-pin. Example: 123456789012345678
pinTitle	string	⚠️	"Check this out!"	Title for the new pin. Required for create-pin. Trimmed to 100 chars
pinDescription	string	❌	—	Description for the new pin. Trimmed to 500 chars
imageUrl	string	⚠️	—	Public, direct image URL for the pin. Required for create-pin
linkUrl	string	❌	—	Destination URL when a user clicks the pin
maxItems	integer	❌	25	Max boards/pins to return for list modes. Range 1–250

⚠️ = conditionally required depending on the selected mode.

Input Example — List Boards

{
  "mode": "list-boards",
  "accessToken": "<YOUR_PINTEREST_ACCESS_TOKEN>",
  "maxItems": 25
}

Input Example — Get User Pins

{
  "mode": "get-user-pins",
  "accessToken": "<YOUR_PINTEREST_ACCESS_TOKEN>",
  "boardId": "123456789012345678",
  "maxItems": 50
}

Input Example — Create Pin

{
  "mode": "create-pin",
  "accessToken": "<YOUR_PINTEREST_ACCESS_TOKEN>",
  "boardId": "123456789012345678",
  "pinTitle": "Summer recipe ideas",
  "pinDescription": "10 easy summer recipes to try this weekend.",
  "imageUrl": "https://example.com/summer-recipes.jpg",
  "linkUrl": "https://myblog.com/summer-recipes"
}

📤 Output

The output fields depend on the selected mode. Every record also carries a scrapedAt ISO 8601 timestamp.

list-boards — one record per board

Field	Type	Description
id	string	Board ID
name	string	Board name
description	string | null	Board description
pinCount	number	Number of pins on the board
followerCount	number	Number of followers
privacy	string	Board privacy (e.g., PUBLIC, SECRET)
createdAt	string	Board creation timestamp
owner	string | null	Owner username
scrapedAt	string	ISO 8601 timestamp

get-user-pins — one record per pin

Field	Type	Description
id	string	Pin ID
title	string | null	Pin title
description	string | null	Pin description
link	string | null	Pin destination link
mediaUrl	string | null	Original media (image) URL
createdAt	string	Pin creation timestamp
boardId	string	The board the pin belongs to
scrapedAt	string	ISO 8601 timestamp

create-pin — one record for the created pin

Field	Type	Description
id	string	New pin ID
title	string	Pin title
description	string | null	Pin description
link	string | null	Pin destination link
boardId	string	Board the pin was created on
createdAt	string	Pin creation timestamp
status	string	Always "CREATED" on success
scrapedAt	string	ISO 8601 timestamp

Output Example — List Boards

{
  "id": "987654321098765432",
  "name": "Recipes",
  "description": "My favorite recipes",
  "pinCount": 142,
  "followerCount": 38,
  "privacy": "PUBLIC",
  "createdAt": "2025-08-14T10:21:00Z",
  "owner": "myusername",
  "scrapedAt": "2026-06-06T12:00:00.000Z"
}

Output Example — Create Pin

{
  "id": "111222333444555666",
  "title": "Summer recipe ideas",
  "description": "10 easy summer recipes to try this weekend.",
  "link": "https://myblog.com/summer-recipes",
  "boardId": "123456789012345678",
  "createdAt": "2026-06-06T12:00:00Z",
  "status": "CREATED",
  "scrapedAt": "2026-06-06T12:00:00.000Z"
}

💡 If no accessToken is provided, the actor writes a single setup guide record (setup_status: "CREDENTIALS_REQUIRED") with step-by-step instructions. If a list query returns zero items, it writes a diagnostic guide record (setup_status: "DIAGNOSTIC_GUIDE") listing likely causes and fixes — neither of these is billed.

📋 Use Cases

• Content scheduling — Programmatically publish pins from your CMS, spreadsheet, or e-commerce feed
• Board auditing — Export all your boards with pin counts and follower numbers for reporting
• Pin backup / migration — Read every pin (title, link, media URL) from a board to archive or move it
• Affiliate & marketing automation — Create pins that link image creatives to product or campaign URLs
• Catalog publishing — Loop a product feed into create-pin runs to populate themed boards
• Workflow integration — Wire the actor into Make, n8n, or Zapier to trigger pin creation on new content

❓ FAQ

Q: Do I need a Pinterest access token? A: Yes. This actor uses the official Pinterest API v5 and requires your own OAuth2 access token. Create an app at developers.pinterest.com, enable the relevant scopes, and paste the token into the accessToken (secret) field.

Q: Which scopes does my token need? A: boards:read for list-boards and get-user-pins, and pins:write to use create-pin. Reading pins also benefits from pins:read. A 403 error usually means a scope is missing.

Q: What image can I use for create-pin? A: A direct, publicly accessible image URL (e.g., https://.../image.jpg). Pinterest fetches the image from that URL (media_source.source_type: image_url); local files are not supported.

Q: Are there length limits on pin text? A: Yes. The pin title is trimmed to 100 characters and the description to 500 characters before being sent to Pinterest.

Q: How many boards or pins can one run return? A: Up to maxItems (default 25, range 1–250). The actor pages through results in batches of 25 using Pinterest's bookmark cursor until it hits your limit or runs out of data.

Q: Why did my run finish with only a "diagnostic" record and no data? A: That means the query returned zero items — typically because the account has no boards, the boardId is wrong or has no public pins, or the token lacks pins:read. The diagnostic record lists the exact remediation steps. Diagnostic/setup records are never charged.

💰 Pricing

This actor uses Pay Per Event (PPE). You are charged per successfully returned item:

Event	When it fires
item-fetched	Per board or pin returned in list-boards / get-user-pins mode
pin-created	Per pin successfully created in create-pin mode

Setup-guide and diagnostic-guide records (missing token or zero results) are not charged. See current per-event prices on the Apify Store page: https://apify.com/viralanalyzer/pinterest-content-scheduler

You also pay Apify platform usage (compute units) as with any actor.

🔗 Related Actors

• Influencer Discovery Agent — Find creators across social platforms
• Instagram Reels Scraper — Extract Reels content and metrics
• RSS News Intelligence — Content monitoring at scale
• ViralAnalyzer Store — Full social & affiliate toolkit

📝 Changelog

v1.0 (Current)

• ✅ list-boards mode — boards with name, description, pin/follower counts, privacy, owner
• ✅ get-user-pins mode — pins per board with title, description, link, original media URL
• ✅ create-pin mode — publish a pin from a public image URL with title/description/link
• ✅ Official Pinterest API v5 integration (BYOC OAuth2 token)
• ✅ Cursor-based pagination up to maxItems (1–250)
• ✅ Setup-guide guard when the access token is missing
• ✅ Zero-result diagnostic guard for list modes
• ✅ Explicit 401 / 403 / 404 / 429 error mapping
• ✅ PPE billing (item-fetched / pin-created) with owner-skip

---

📌 Pinterest Content Scheduler — Listar Boards, Ler Pins & Criar/Agendar Pins via Pinterest API v5

🇺🇸 English | 🇧🇷 Português

Gerencie seu conteúdo do Pinterest pela API oficial v5. Liste seus boards, leia os pins dentro de um board e crie (publique) novos pins a partir de uma URL pública de imagem — tudo com um único token de acesso OAuth2. Traga seu próprio token (BYOC), escolha um modo e o actor retorna registros limpos e estruturados, prontos para o seu pipeline.

✨ Funcionalidades

• 📋 Listar boards — Recupere seus boards do Pinterest com nome, descrição, contagem de pins, seguidores, privacidade e dono
• 🖼️ Ler pins do board — Liste os pins dentro de um board específico com título, descrição, link e URL da mídia original
• ➕ Criar pins — Publique um novo pin em um board a partir de uma URL pública de imagem, com título, descrição e link de destino
• 🔑 API v5 oficial — Fala diretamente com api.pinterest.com/v5 (sem scraping, sem navegador)
• 🔒 Credenciais Próprias (BYOC) — Usa seu próprio token OAuth2 do Pinterest (armazenado como input secreto)
• 📄 Paginação automática — Paginação baseada em cursor (bookmark) por boards e pins até o limite maxItems
• 🛟 Guardas autodiagnósticas — Se o token estiver ausente ou a consulta retornar zero itens, o actor grava um guia de setup/diagnóstico no dataset em vez de falhar silenciosamente
• ⏱️ Mapeamento claro de erros — Mensagens amigáveis para 401 (token inválido), 403 (escopos faltando), 404 e 429 (limite de taxa)

📥 Entrada

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
mode	string (enum)	✅	"list-boards"	Operação: list-boards, get-user-pins ou create-pin
accessToken	string (secreto)	✅	—	Token OAuth2 do Pinterest em developers.pinterest.com (precisa de boards:read e/ou pins:write)
boardId	string	⚠️	—	ID do board alvo. Obrigatório para get-user-pins e create-pin. Ex: 123456789012345678
pinTitle	string	⚠️	"Check this out!"	Título do novo pin. Obrigatório para create-pin. Cortado em 100 caracteres
pinDescription	string	❌	—	Descrição do novo pin. Cortada em 500 caracteres
imageUrl	string	⚠️	—	URL pública e direta da imagem do pin. Obrigatória para create-pin
linkUrl	string	❌	—	URL de destino quando o usuário clica no pin
maxItems	integer	❌	25	Máximo de boards/pins nos modos de listagem. Faixa 1–250

⚠️ = condicionalmente obrigatório, conforme o mode selecionado.

Exemplo de Entrada — Listar Boards

{
  "mode": "list-boards",
  "accessToken": "<SEU_TOKEN_DE_ACESSO_PINTEREST>",
  "maxItems": 25
}

Exemplo de Entrada — Obter Pins do Usuário

{
  "mode": "get-user-pins",
  "accessToken": "<SEU_TOKEN_DE_ACESSO_PINTEREST>",
  "boardId": "123456789012345678",
  "maxItems": 50
}

Exemplo de Entrada — Criar Pin

{
  "mode": "create-pin",
  "accessToken": "<SEU_TOKEN_DE_ACESSO_PINTEREST>",
  "boardId": "123456789012345678",
  "pinTitle": "Ideias de receitas de verão",
  "pinDescription": "10 receitas fáceis de verão para testar no fim de semana.",
  "imageUrl": "https://example.com/receitas-verao.jpg",
  "linkUrl": "https://meublog.com/receitas-verao"
}

📤 Saída

Os campos de saída dependem do mode selecionado. Todo registro também carrega um timestamp scrapedAt em ISO 8601.

list-boards — um registro por board

Campo	Tipo	Descrição
id	string	ID do board
name	string	Nome do board
description	string | null	Descrição do board
pinCount	número	Quantidade de pins no board
followerCount	número	Quantidade de seguidores
privacy	string	Privacidade do board (ex: PUBLIC, SECRET)
createdAt	string	Timestamp de criação do board
owner	string | null	Username do dono
scrapedAt	string	Timestamp ISO 8601

get-user-pins — um registro por pin

Campo	Tipo	Descrição
id	string	ID do pin
title	string | null	Título do pin
description	string | null	Descrição do pin
link	string | null	Link de destino do pin
mediaUrl	string | null	URL da mídia (imagem) original
createdAt	string	Timestamp de criação do pin
boardId	string	Board ao qual o pin pertence
scrapedAt	string	Timestamp ISO 8601

create-pin — um registro para o pin criado

Campo	Tipo	Descrição
id	string	ID do novo pin
title	string	Título do pin
description	string | null	Descrição do pin
link	string | null	Link de destino do pin
boardId	string	Board onde o pin foi criado
createdAt	string	Timestamp de criação do pin
status	string	Sempre "CREATED" em caso de sucesso
scrapedAt	string	Timestamp ISO 8601

Exemplo de Saída — Listar Boards

{
  "id": "987654321098765432",
  "name": "Receitas",
  "description": "Minhas receitas favoritas",
  "pinCount": 142,
  "followerCount": 38,
  "privacy": "PUBLIC",
  "createdAt": "2025-08-14T10:21:00Z",
  "owner": "meuusuario",
  "scrapedAt": "2026-06-06T12:00:00.000Z"
}

Exemplo de Saída — Criar Pin

{
  "id": "111222333444555666",
  "title": "Ideias de receitas de verão",
  "description": "10 receitas fáceis de verão para testar no fim de semana.",
  "link": "https://meublog.com/receitas-verao",
  "boardId": "123456789012345678",
  "createdAt": "2026-06-06T12:00:00Z",
  "status": "CREATED",
  "scrapedAt": "2026-06-06T12:00:00.000Z"
}

💡 Se nenhum accessToken for fornecido, o actor grava um único registro de guia de configuração (setup_status: "CREDENTIALS_REQUIRED") com instruções passo a passo. Se uma consulta de listagem retornar zero itens, ele grava um registro de guia de diagnóstico (setup_status: "DIAGNOSTIC_GUIDE") com causas prováveis e correções — nenhum dos dois é cobrado.

📋 Casos de Uso

• Agendamento de conteúdo — Publique pins programaticamente a partir do seu CMS, planilha ou feed de e-commerce
• Auditoria de boards — Exporte todos os seus boards com contagem de pins e seguidores para relatórios
• Backup / migração de pins — Leia todos os pins (título, link, URL da mídia) de um board para arquivar ou migrar
• Automação de afiliados & marketing — Crie pins que ligam criativos de imagem a URLs de produto ou campanha
• Publicação de catálogo — Itere um feed de produtos em execuções create-pin para popular boards temáticos
• Integração de workflows — Conecte o actor ao Make, n8n ou Zapier para criar pins ao surgir novo conteúdo

❓ Perguntas Frequentes

P: Preciso de um token de acesso do Pinterest? R: Sim. Este actor usa a API oficial v5 do Pinterest e exige seu próprio token OAuth2. Crie um app em developers.pinterest.com, habilite os escopos relevantes e cole o token no campo accessToken (secreto).

P: Quais escopos meu token precisa? R: boards:read para list-boards e get-user-pins, e pins:write para usar create-pin. Ler pins também se beneficia de pins:read. Um erro 403 geralmente indica escopo faltando.

P: Qual imagem posso usar no create-pin? R: Uma URL de imagem direta e publicamente acessível (ex: https://.../imagem.jpg). O Pinterest busca a imagem nessa URL (media_source.source_type: image_url); arquivos locais não são suportados.

P: Há limites de tamanho no texto do pin? R: Sim. O título é cortado em 100 caracteres e a descrição em 500 caracteres antes de serem enviados ao Pinterest.

P: Quantos boards ou pins uma execução pode retornar? R: Até maxItems (padrão 25, faixa 1–250). O actor pagina os resultados em lotes de 25 usando o cursor bookmark do Pinterest até atingir seu limite ou esgotar os dados.

P: Por que minha execução terminou só com um registro de "diagnóstico" e sem dados? R: Isso significa que a consulta retornou zero itens — normalmente porque a conta não tem boards, o boardId está errado ou sem pins públicos, ou o token não tem pins:read. O registro de diagnóstico lista os passos exatos de correção. Registros de diagnóstico/setup nunca são cobrados.

💰 Preços

Este actor usa Pay Per Event (PPE). Você é cobrado por item retornado com sucesso:

Evento	Quando dispara
item-fetched	Por board ou pin retornado nos modos list-boards / get-user-pins
pin-created	Por pin criado com sucesso no modo create-pin

Registros de guia de configuração e de diagnóstico (token ausente ou zero resultados) não são cobrados. Veja os preços por evento atuais na página do Apify Store: https://apify.com/viralanalyzer/pinterest-content-scheduler

Você também paga o uso da plataforma Apify (compute units), como em qualquer actor.

🔗 Actors Relacionados

• Influencer Discovery Agent — Encontre criadores em plataformas sociais
• Instagram Reels Scraper — Extraia conteúdo e métricas de Reels
• RSS News Intelligence — Monitoramento de conteúdo em escala
• Loja ViralAnalyzer — Toolkit social & de afiliados completo

📝 Changelog

v1.0 (Atual)

• ✅ Modo list-boards — boards com nome, descrição, contagem de pins/seguidores, privacidade, dono
• ✅ Modo get-user-pins — pins por board com título, descrição, link, URL da mídia original
• ✅ Modo create-pin — publica um pin a partir de URL pública de imagem com título/descrição/link
• ✅ Integração com a API oficial v5 do Pinterest (token OAuth2 BYOC)
• ✅ Paginação por cursor até maxItems (1–250)
• ✅ Guarda de guia de configuração quando o token está ausente
• ✅ Guarda de diagnóstico para zero resultados nos modos de listagem
• ✅ Mapeamento explícito de erros 401 / 403 / 404 / 429
• ✅ Cobrança PPE (item-fetched / pin-created) com owner-skip