Getting Board IDs
Before scheduling Pinterest posts, you need to fetch the available boards for your Pinterest account. The boardId is required when scheduling pins.
Query Pinterest Boards
Use the pinterestBoards query to fetch all boards for a connected Pinterest account:
query pinterestBoards($socialAccountId: ID!) {
pinterestBoards(socialAccountId: $socialAccountId) {
id
name
privacy
}
}
{
"socialAccountId": "your-social-account-id"
}
{
"data": {
"pinterestBoards": [
{
"id": "123456789",
"name": "Recipes",
"privacy": "PUBLIC"
},
{
"id": "987654321",
"name": "Home Decor",
"privacy": "PUBLIC"
},
{
"id": "456789123",
"name": "Travel Inspiration",
"privacy": "SECRET"
}
]
}
}
socialAccounts query to get the ID of your connected Pinterest account. Look for accounts where platform is "PINTEREST".Scheduling Posts
Mutation
Use the schedulePinterestPost mutation to schedule pins to Pinterest boards:
mutation SchedulePinterestPost($input: SchedulePinterestPostInput!) {
schedulePinterestPost(input: $input) {
success
errors {
field
message
}
post {
id
socialAccount {
id
username
}
publishingStatus
title
description
link
dominantColor
note
boardId
gallery {
id
galleryMediaSet {
id
media {
url
mimeType
}
}
}
submissions {
id
postAt
}
}
}
}
Input Parameters
SchedulePinterestPostInput
SPECIFIC_TIME, QUEUE_NEXT (default: SPECIFIC_TIME).
Only accepted when scheduling a new post. See Scheduling at the Next Open Slot.pinterestBoards query to fetch available boards and their IDs.id, name, or url. See Attaching Media.
Only supported when scheduling new posts, not when updating existing ones.READY_TO_PUBLISH, DRAFT (default: READY_TO_PUBLISH)PinterestPostSubmissionInputType
Each submission defines a specific posting schedule:
schedulingMode: QUEUE_NEXT on the post when scheduling a new one, or the post is a draft.
See Drafts without a date.Examples
Simple Pinterest Pin
Schedule a basic Pinterest pin with an image from URL.
{
"input": {
"username": "mybrand",
"title": "Delicious Chocolate Chip Cookies Recipe",
"description": "Easy homemade chocolate chip cookies that are crispy on the outside and chewy on the inside. Perfect for any occasion! Get the full recipe on our blog.",
"link": "https://example.com/chocolate-chip-cookies-recipe",
"media": [{ "url": "https://example.com/cookie-image.jpg" }],
"boardId": "123456789",
"submissions": [
{
"postAt": "2025-12-01T15:00:00Z"
}
]
}
}
Scheduling at the Next Open Slot
Instead of picking a time yourself, pass schedulingMode: QUEUE_NEXT and leave postAt out. Postpone puts the pin in the next open slot on the account's Account Schedule, skipping any slot that already has a post on it.
{
"input": {
"username": "mybrand",
"schedulingMode": "QUEUE_NEXT",
"title": "Delicious Chocolate Chip Cookies Recipe",
"description": "This one goes out at my next open slot.",
"link": "https://example.com/chocolate-chip-cookies-recipe",
"media": [{ "url": "https://example.com/cookie-image.jpg" }],
"boardId": "123456789",
"submissions": [{}]
}
}
Leave postAt off the submissions — the resolved slot becomes the date for all of them.
The account needs a schedule set up for this to work, postAt and QUEUE_NEXT can't be combined, and updateScheduledPinterestPost rejects schedulingMode. See Scheduling at the Next Open Slot for the full rules.
Pinterest Pin with Content Library Media
Schedule a pin using an image from your Content Library. Reference the file by its id, which every upload mutation returns.
{
"input": {
"username": "mybrand",
"title": "10 Home Decor Ideas for Small Spaces",
"description": "Transform your small space with these creative and budget-friendly home decor ideas. From storage solutions to color schemes, we've got you covered! #homedecor #smallspaces #interiordesign",
"link": "https://example.com/small-space-decor-ideas",
"media": [{ "id": "1046" }],
"dominantColor": "#F4E4BC",
"boardId": "987654321",
"submissions": [
{
"postAt": "2025-12-01T18:30:00Z"
}
]
}
}
You can also reference the file by name. Names are matched case-insensitively and the first match wins, so prefer id when several files share a name.
{
"media": [{ "name": "small-space-decor.jpg" }]
}
Pinterest Pin with Board Section
Schedule a pin to a specific section within a board.
{
"input": {
"username": "mybrand",
"title": "Summer Wedding Centerpiece Ideas",
"description": "Beautiful and elegant centerpiece ideas perfect for summer weddings. These floral arrangements will add the perfect touch to your special day.",
"link": "https://example.com/summer-wedding-centerpieces",
"media": [{ "url": "https://example.com/wedding-centerpiece.jpg" }],
"boardId": "456789123",
"boardSectionId": "789123456",
"submissions": [
{
"postAt": "2025-12-01T12:00:00Z"
}
]
}
}
Pinterest Pin with Private Note
Schedule a pin with a private note for internal organization.
{
"input": {
"username": "mybrand",
"title": "Best Travel Destinations 2024",
"description": "Discover the most amazing travel destinations for 2024! From hidden gems to popular hotspots, plan your next adventure with our comprehensive guide.",
"link": "https://example.com/travel-destinations-2024",
"media": [{ "url": "https://example.com/travel-destinations.jpg" }],
"note": "Part of Q4 travel content campaign - scheduled for peak engagement time",
"dominantColor": "#4A90E2",
"boardId": "321654987",
"submissions": [
{
"postAt": "2025-12-01T20:00:00Z"
}
]
}
}
Fashion Pinterest Pin
Schedule a fashion-related pin with rich description and keywords.
{
"input": {
"username": "fashionbrand",
"title": "Cozy Fall Outfit Ideas for 2024",
"description": "Stay stylish and comfortable this fall with these cozy outfit ideas! Perfect combinations of sweaters, boots, and accessories for the season. #falloutfits #fashion2024 #cozystyle #autumn #ootd",
"link": "https://example.com/fall-fashion-2024",
"media": [{ "id": "1047" }],
"dominantColor": "#D2691E",
"boardId": "159753468",
"submissions": [
{
"postAt": "2025-12-01T16:45:00Z"
}
]
}
}
Response Types
Success Response
{
"data": {
"schedulePinterestPost": {
"success": true,
"errors": [],
"post": {
"id": "123",
"socialAccount": {
"id": "456",
"username": "mybrand"
},
"publishingStatus": "READY_TO_PUBLISH",
"title": "Delicious Chocolate Chip Cookies Recipe",
"description": "Easy homemade chocolate chip cookies that are crispy on the outside and chewy on the inside. Perfect for any occasion! Get the full recipe on our blog.",
"link": "https://example.com/chocolate-chip-cookies-recipe",
"dominantColor": null,
"note": null,
"boardId": "123456789",
"boardSectionId": null,
"gallery": {
"id": "789",
"media": [
{
"id": "101",
"url": "https://cdn.example.com/cookie-image.jpg",
"type": "image"
}
]
},
"submissions": [
{
"id": "112",
"postAt": "2025-12-01T15:00:00Z"
}
]
}
}
}
}
Error Response
{
"data": {
"schedulePinterestPost": {
"success": false,
"errors": [
{
"field": "title",
"message": "Pinterest pin titles cannot exceed 100 characters."
}
],
"post": null
}
}
}
Updating a Post
To update an existing scheduled post, use the same input type with the corresponding update mutation and include the post id:
mutation UpdateScheduledPinterestPost($input: SchedulePinterestPostInput!) {
updateScheduledPinterestPost(input: $input) {
success
errors {
field
message
}
post {
id
}
}
}
Pass the id of the post you want to update in the input, along with the fields you want to change:
{
"input": {
"id": "12345",
"username": "myhandle",
"title": "Updated Pin Title",
"submissions": [{"postAt": "2025-12-01T15:30:00Z"}]
}
}
id field to specify which post to update. Only scheduled posts that have not been published yet can be updated.postAt is required on an update, so every update states the date the post goes out on — pass the date it already has to leave it where it is. A draft staying a draft is exempt, and a draft you're promoting to READY_TO_PUBLISH needs a date of your choosing; see Drafts without a date.
schedulingMode is not accepted on an update at all; see Scheduling at the Next Open Slot.
Validation Rules
- Title Length: Maximum 100 characters
- Description Length: Maximum 500 characters
- Image Requirements: JPEG, PNG, or GIF format
- Image Size: Minimum 600x900 pixels, maximum 1000x1500 pixels recommended
- Aspect Ratio: 2:3 aspect ratio performs best (e.g., 1000x1500)
- File Size: Maximum 20MB per image
- Link Requirements: Must be a valid, accessible URL
- Board Access: Must have write access to the specified board
- Content Quality: Images should be high-quality and relevant to the title/description
- Scheduling: Posts must be scheduled for future dates only
- Account Limits: Respects your plan's monthly pin limits
Common Errors
The specified username is not connected to your Postpone account. Connect the account in your settings first.
Your pin title is too long. Keep titles under 100 characters for optimal display.
You must include an image. Use media to attach an image to your pin.
Your image format is not supported. Use JPEG, PNG, or GIF format for Pinterest pins.
Your image file is too large. Pinterest supports images up to 20MB in size.
Your image is too small. Pinterest requires images to be at least 600x900 pixels for optimal performance.
The specified board ID is invalid or you don't have write access to this board. Check your board permissions.
The specified board section ID doesn't exist or isn't accessible. Verify the section ID is correct.
The provided link is not a valid URL. Ensure your link starts with http:// or https://.
Your pin description is too long. Keep descriptions under 500 characters.
The postAt timestamp must be in the future. Check your timezone settings.
A new post has to say when it goes out: pass a postAt, or schedulingMode: QUEUE_NEXT. Drafts are exempt: leave postAt off one and it is parked on a placeholder date about 30 days out.
schedulingMode isn't accepted on an update, so a postAt is the only way to say when the post goes out. You'll also see it when promoting a parked draft to publishingStatus: READY_TO_PUBLISH without giving it a date.
schedulingMode: QUEUE_NEXT needs an Account Schedule on the account you're posting to. Set one up, or pass an explicit postAt.
schedulingMode is only accepted when scheduling a new post. To move a post that is already scheduled, pass a postAt to updateScheduledPinterestPost.
You've reached your plan's Pinterest pin limit for the scheduled month. Upgrade your plan or schedule for a different month.