Calendar
Read scheduled, published and draft slots in one call, to avoid collisions before scheduling more content.
Preview
Preview: the API and MCP server are in private beta; details may change.
GET /calendar returns a lightweight summary of scheduled, published and draft slots in the workspace's own timezone, meant for an agent to check before filling in more content with Posts batch, rather than the full detail of GET /posts/{id}. It backs the MCP tool get_calendar.
Required scope: posts:read.
Endpoint
| Method | Path | Description |
|---|---|---|
| GET | /calendar | List scheduled/published/draft slots for a date range |
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
from | string (date) | Yes | Start of the range |
to | string (date) | Yes | End of the range. Range is limited to 90 days per call |
profile_id | string | Yes | The profile to read the calendar for |
curl "https://api.getimma.com/v1/calendar?from=2026-10-01&to=2026-10-31&profile_id=prof_01J..." \
-H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx"Response:
{
"timezone": "Asia/Jakarta",
"slots": [
{
"post_id": "post_01J...",
"scheduled_at": "2026-10-01T18:30:00+07:00",
"status": "scheduled",
"platforms": ["instagram", "tiktok"],
"caption_preview": "Rendang 1 kg, pre-order..."
}
]
}Drafts created through Posts batch or the MCP tool create_posts_batch appear here the same way as any other draft, there is no separate calendar for AI-created content.
Errors
| Code | HTTP | When |
|---|---|---|
unauthorized | 401 | Missing or invalid API key |
insufficient_scope | 403 | Key lacks posts:read |
invalid_range | 400 | from/to range exceeds 90 days, or to is before from |
See Errors for the shared error shape.
Platform notes
This endpoint has no platform specific behavior; it summarizes posts across TikTok, Instagram, Facebook Pages and Threads uniformly. For per-platform posting limits that affect where you can safely schedule a new slot, see Platform rules.