CoSchedule

A description of one CoSchedule calendar: its statuses, labels, project types, team members and tags, each with the id it is known by. Call this before filtering or interpreting a list — projects carry ids, and this is what turns them into names and back. timezone and dateFormat are how this calendar reads a date. Every list also carries a display field beside each timestamp — scheduleDisplay, dueDateDisplay, sentTimeDisplay, completedAtDisplay, approvedAtDisplay, deniedAtDisplay — already written this way, so use those rather than converting unix seconds yourself. Only labels this user may see are returned. Call whoami first for the calendarId.

describe_calendar

Follower and review numbers for the social profiles on a CoSchedule calendar. Answers "how many followers do we have", "did we grow", and "what does the curve look like". totalFollowers is a running count, not a change: read the calendar total from the totalFollowers field on the response and never add up the rows yourself, and never sum it across days. For followers gained or lost pass include {"growth":true} and read growthTotals — those are per-period changes and do add up. Pass include {"history":true} for one count per profile per day. The numbers belong to the connected account, which may be on more than one calendar. With no date, growth and history cover the last 30 days. Only profiles this user may see are counted, and none at all without social access. Call whoami first for the calendarId.

get_follower_stats

Engagement totals across the sent messages on a CoSchedule calendar: impressions, likes, comments, shares and clicks. Answers "how did we do last month" and "is engagement improving". The totals cover every message the filter matches, not one page, so read them from here rather than adding up rows from list_messages. Pass include {"byNetwork":true} to compare platforms, {"byProfile":true} for each connected account, and {"series":true} with granularity day, week or month for a series over time — ask for the bucket you want rather than one call per period. For "what is the best day or time to post" pass include {"byDayOfWeek":true} or {"byHourOfDay":true}: these group by when the post went out, which the series cannot tell you because it records when engagement arrived. Compare engagementsPerMessage rather than the totals — the slots hold different numbers of posts, so a total just names the busiest. Say how many posts a slot holds when you report it; a handful is not a pattern. Unsent messages have no engagement and are never counted. With no date the series covers the last 30 days. Only messages on profiles this user may see are counted. Call whoami first for the calendarId.

get_message_engagement

Images and videos in a CoSchedule calendar's Assets, newest first. Pass type for only images or only videos, and search to find one by name, description or alt text — one call, where paging the library to find a named asset is many. Each asset carries its size, dimensions and duration, which decide whether a network accepts it, and url opens it in CoSchedule. status is ready, processing (a video still being prepared; it cannot be attached yet) or failed. Archived assets are never returned. Without type, paging stops at offset 1000; pass type to page further. Call whoami first for the calendarId.

list_assets

Marketing campaigns on a CoSchedule calendar. A campaign is a container that projects belong to, and it spans a date range rather than a single date. Campaigns have no status of any kind. Pass date to narrow by period: a campaign counts when it overlaps the period, so one that ran from June to August is returned for July. Pass filter to narrow by title, label or owner — searching by title is one call, where paging the calendar to find a named campaign is many. To list what is in a campaign, call list_projects with its id as marketingCampaignId. Call whoami first for the calendarId, and describe_calendar for label and team member ids.

list_campaigns

Projects on a CoSchedule calendar: blog posts and other content, plus WordPress posts. Marketing campaigns are not projects — they contain projects — so use list_campaigns for those. Results are ordered by schedule date, earliest first, with unscheduled projects last. Pass date to narrow by time — {"relative":"overdue"} for late work, {"relative":"unscheduled"} for work with no date, or a {"from","to"} range for any period. With no date the answer covers the last 30 days and everything upcoming, and appliedFilter comes back with defaulted true — say so, and offer to look further back rather than presenting it as the whole calendar. Pass filter to narrow by title, status, label, project type, owner or campaign — searching by title is one call, where paging the calendar to find a named project is many. Only projects this user may see are returned. Call whoami first for the calendarId.

list_projects

Social messages on a CoSchedule calendar: the posts scheduled to go out on connected profiles. Ordered by the date they are scheduled for. Only messages on profiles this user may see are returned, and none at all if they do not have social access. Pass include {"stats":true} for each message engagement so far, which is left out otherwise. For a total across many messages call get_message_engagement instead of adding these up. To find the best or worst performing, sort by impressions — or by score, which is a weighted engagement measure rather than a count — with a small limit rather than paging through everything. Sorting by an engagement number returns the stats it ranked by, counts only messages with engagement recorded, and makes total the number measured, which is fewer than the number sent — say measured rather than sent when you quote it. Call whoami first for the calendarId, and describe_calendar for label ids.

list_messages

The social accounts connected to a CoSchedule calendar, with their connection health. requiresReauthentication is usually the answer to "why did my post not go out". Only profiles this user may see are returned, and none at all without social access. Call whoami first for the calendarId.

list_social_profiles

Tasks on a CoSchedule calendar. A task hangs off a project or a campaign and has its own assignee, due date and approval. Outstanding work only unless completed says otherwise. Results are ordered by due date, earliest first, with undated tasks last. Pass include {"subtasks":true} to get each task checklist, which is left out otherwise. Calendar tasks only — personal to-dos, which belong to a user rather than a calendar, are not here. completedAt is when a task was actually finished: compare it with dueDate to say whether work landed on time, rather than counting completed tasks as if that measured anything. A completed task can still have completedAt null, because an approver can complete one nobody marked done — treat that as unknown rather than late. completedByName can differ from the assignee. approvedAt and deniedAt are the approval outcome: on a task with an approverTeamMemberId, neither set means it is still awaiting one; a task with no approver needs none. Only tasks this user may see are returned. Call whoami first for the calendarId, and describe_calendar for label and team member ids.

list_tasks

The signed-in CoSchedule user and every calendar they can reach, with their team member id on each. Call this first: every other tool needs a calendarId, and this is where they come from.

whoami