How to Integrate Retool with CoSchedule

CoSchedule provides API access through a token-based system accessible from the account settings. Log in to your CoSchedule account and navigate to the account menu in the top-right corner. Select Settings, then scroll to find the Integrations or API section. In CoSchedule Marketing Calendar, API keys are found under Settings → Apps & Integrations → API. If you do not see an API option, verify your CoSchedule plan includes API access — the Marketing Calendar and Marketing Suite plans include API access, while lower-tier plans may not. Click Generate API Token or New Token to create a new key. Give the token a descriptive name like 'Retool Integration'. Copy the generated API key immediately and store it securely — CoSchedule typically shows the full key only once at generation time, requiring regeneration if lost. The API key is used as a Bearer token in the Authorization header of every API request. Store this value in a Retool Configuration Variable: navigate to Retool Settings → Configuration Variables, create a variable named COSCHEDULE_API_KEY, paste the value, and enable the 'Is Secret' checkbox to restrict it from frontend exposure. You will also need your CoSchedule organization ID for some API endpoints — this can be found in the URL when you are logged in to CoSchedule (e.g., coschedule.com/calendar/{organizationId}/...) or in the API documentation for your account.

In Retool, click the Resources tab in the sidebar and select Add Resource. Choose REST API as the resource type. Name the resource 'CoSchedule API'. Set the Base URL to https://api.coschedule.com. For authentication, select Bearer Token from the Authentication dropdown. In the Bearer Token field, enter {{ retoolContext.configVars.COSCHEDULE_API_KEY }} to reference the Configuration Variable stored in the previous step rather than pasting the raw token value directly. This ensures the API key is managed centrally and not embedded in resource configuration as visible text. Add a default header: Content-Type with value application/json. This header is required for POST and PATCH requests and is safe to include globally. If CoSchedule's API requires an organization ID in request paths or headers, add it as a default URL parameter: organization_id → your CoSchedule org ID value. Click Save Resource. To verify the connection works, open a new Retool app, create a query using the CoSchedule API resource, set Method to GET and Path to /calendar_items, add URL parameters for date_range_start and date_range_end with date values, then click Preview. A successful connection returns calendar items from your CoSchedule calendar.

Create the core calendar data queries. Create a query named 'getCalendarItems'. Set Method to GET and Path to /calendar_items. Add URL parameters: date_range_start → {{ dateRangePicker.value[0] || new Date().toISOString().split('T')[0] }} (today as default), date_range_end → {{ dateRangePicker.value[1] || new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0] }} (30 days from today as default). CoSchedule returns calendar items as an array where each item has: id, title, type (blog-post, social-campaign, email, task, event, etc.), status (idea, in-progress, review, approved, scheduled, published), scheduled_date, assignees (array of team member objects), color, and social_messages (array). Create a transformer named 'normalizeCalendarItems' that flattens this nested structure into table-friendly rows. The transformer maps each item to: id, title, type (humanized), status, scheduled_date (formatted), assignee_names (joined from assignees array), days_until_publish (computed from scheduled_date vs today), and is_overdue (boolean: scheduled_date < today AND status is not 'published'). Add a computed field overdue_flag that returns 'Overdue' when is_overdue is true and 'On Track' otherwise — this powers conditional formatting in the Retool Table. Create a second query named 'getProjects'. Set Method to GET and Path to /projects with similar date parameters. Projects represent larger marketing campaigns that group multiple calendar items.

1// Transformer: normalize CoSchedule calendar items
2const items = data || [];
3const today = new Date();
4today.setHours(0, 0, 0, 0);
5
6const STATUS_ORDER = {
7  'idea': 1, 'in-progress': 2, 'needs-review': 3,
8  'approved': 4, 'scheduled': 5, 'published': 6
9};
10
11return items.map(item => {
12  const scheduledDate = item.scheduled_date
13    ? new Date(item.scheduled_date)
14    : null;
15  const daysUntil = scheduledDate
16    ? Math.ceil((scheduledDate - today) / (1000 * 60 * 60 * 24))
17    : null;
18  const isOverdue = scheduledDate && daysUntil < 0
19    && item.status !== 'published';
20  return {
21    id: item.id,
22    title: item.title || '(Untitled)',
23    type: item.type ? item.type.replace(/-/g, ' ') : 'Unknown',
24    status: item.status || 'unknown',
25    status_order: STATUS_ORDER[item.status] || 0,
26    scheduled_date: scheduledDate
27      ? scheduledDate.toLocaleDateString()
28      : 'Not set',
29    days_until: daysUntil !== null ? daysUntil : 'N/A',
30    assignees: (item.assignees || []).map(a => a.name).join(', ') || 'Unassigned',
31    is_overdue: isOverdue,
32    overdue_flag: isOverdue ? 'Overdue' : 'On Track'
33  };
34}).sort((a, b) => a.status_order - b.status_order);

Create additional queries for the workload and social views. Create a JavaScript query named 'computeWorkloadByAssignee'. This query references getCalendarItems.data and groups items by assignee using JavaScript reduce: iterate over each calendar item's assignees array, increment a counter for each assignee name, and build an array of { name, item_count, overdue_count } objects sorted by item_count descending. This transformer runs client-side in Retool's JavaScript engine without additional API calls. For social message data, create a query named 'getSocialMessages'. Set Method to GET, Path to /social_messages, and URL parameters date_range_start and date_range_end using the same dateRangePicker binding as getCalendarItems. Each social message has: id, message (text content), social_profiles (array of connected networks), scheduled_date, scheduled_time, and calendar_item_id (linking it to a parent item). Create a transformer for social messages that flattens the social_profiles array into a comma-separated string of profile names, formats the scheduled datetime into a human-readable string, and computes a conflict_flag boolean for messages scheduled within 30 minutes of another message on the same profile — this requires sorting by scheduled datetime and comparing adjacent messages for the same profile.

1// JavaScript query: compute workload by assignee
2const items = getCalendarItems.data || [];
3const assigneeMap = {};
4
5items.forEach(item => {
6  const name = item.assignees || 'Unassigned';
7  const assignees = name.split(', ');
8  assignees.forEach(assignee => {
9    if (!assigneeMap[assignee]) {
10      assigneeMap[assignee] = { name: assignee, item_count: 0, overdue_count: 0 };
11    }
12    assigneeMap[assignee].item_count++;
13    if (item.is_overdue) assigneeMap[assignee].overdue_count++;
14  });
15});
16
17return Object.values(assigneeMap).sort((a, b) => b.item_count - a.item_count);

Build the complete Retool dashboard. Add a date range picker component named 'dateRangePicker' at the top, defaulting to today through 30 days from now — this controls all queries. Below the date picker, add a stat bar with three Stat components: Total Items ({{ getCalendarItems.data.length }}), Overdue Items ({{ getCalendarItems.data.filter(i => i.is_overdue).length }}), and Items Scheduled This Week (filter by days_until between 0 and 7). Below the stats, add a Select component for type filtering and an assignee filter, both populating from getCalendarItems.data. Add a Table named 'calendarTable' bound to getCalendarItems.data with columns: title, type, status (tag-styled with color: green for published, blue for scheduled, yellow for review, gray for idea), scheduled_date, days_until (with conditional formatting: red when negative, green when positive and ≤7), and assignees. Enable conditional row coloring: red background for rows where is_overdue is true. On the right side or in a second tab, show the workload view: a Bar Chart bound to computeWorkloadByAssignee.data with name on X and item_count on Y, and a Table of social messages below with message preview, profiles, and scheduled datetime. Add a refresh button that triggers all queries simultaneously. Set getCalendarItems, getSocialMessages, and getProjects to run on page load.