Scheduling & Data Model

Understanding how data is structured helps you build reliable integrations and avoid conflicts with the platform's scheduling engine.

Core Tables

Table	Purpose	Key Fields
`workspaces`	Workspace metadata and plan limits.	`id`, `slug`, `plan`, `timezone`
`members`	Workspace members and roles.	`id`, `workspace_id`, `role`, `permissions`
`social_accounts`	Connected social profiles per workspace.	`id`, `workspace_id`, `platform`, `status`, `token_expires_at`
`posts`	Post drafts, scheduled content, and metadata.	`id`, `workspace_id`, `status`, `publish_at`, `payload`, `author_id`
`post_targets`	Platform-specific settings for each post.	`post_id`, `social_account_id`, `platform_settings`
`media_assets`	Stored media files and derived crops.	`id`, `workspace_id`, `category`, `storage_path`, `usage_count`
`reviews`	Google Business reviews and responses.	`id`, `workspace_id`, `location_id`, `rating`, `sentiment`, `responded_at`
`analytics_snapshots`	Daily metric aggregates per platform.	`workspace_id`, `social_account_id`, `metric`, `value`, `date`

All tables enforce Row Level Security keyed on workspace_id. API responses expose IDs you can reference safely.

Scheduling Lifecycle

Draft: Posts start in status = 'draft' with optional scheduled time.
Scheduled: When publish time is set, the post enters the scheduling queue.
Queued: Five minutes before publish, the scheduler locks the record and prepares payloads for each platform.
Publishing: The scheduler sends payloads to the respective social APIs. Failures trigger retries with exponential backoff (up to 3 attempts).
Published: On success, status = 'published' and published_at stores the actual timestamp per platform.
Failed: After retries, failures are marked with error codes accessible via /posts/{id}/deliveries.

Use webhooks (post.scheduled, post.published, post.failed) to stay synchronized with these transitions.

Conflict Avoidance

Updating a post within 5 minutes of publishing locks the record to prevent conflicting changes. The API returns 409 conflict if you attempt to edit during this window.
Media assets referenced by scheduled posts cannot be deleted until the post publishes or is cancelled.
Cancelling a post removes it from the queue immediately and emits a post.cancelled webhook.

Timezone Considerations

Schedules use the workspace timezone by default; override per post if needed.
The API requires ISO 8601 timestamps with explicit offsets (2025-10-21T12:00:00-04:00).
The scheduler normalizes to UTC internally and respects daylight saving transitions.

Analytics Data Flow

After publishing, delivery receipts update post performance metrics.
Nightly jobs aggregate metrics into analytics_snapshots per platform and workspace.
Saved Views point to snapshot data for fast loading in dashboards and exports.

Integrating Safely

Always fetch the latest post representation before editing to avoid overwriting teammate changes.
Use idempotency keys (Idempotency-Key header) when creating posts to prevent duplicates.
When syncing reviews, use the cursor parameter to fetch only new items since your last sync.

To explore authentication requirements for these operations, revisit Authentication & OAuth. For event-driven updates, pair this guide with Webhooks & Events.

Core Tables

Table

Purpose

Key Fields

workspaces

Workspace metadata and plan limits.

id, slug, plan, timezone

members

Workspace members and roles.

id, workspace_id, role, permissions

social_accounts

Connected social profiles per workspace.

id, workspace_id, platform, status, token_expires_at

posts

Post drafts, scheduled content, and metadata.

id, workspace_id, status, publish_at, payload, author_id

post_targets

Platform-specific settings for each post.

post_id, social_account_id, platform_settings

media_assets

Stored media files and derived crops.

id, workspace_id, category, storage_path, usage_count

reviews

Google Business reviews and responses.

id, workspace_id, location_id, rating, sentiment, responded_at

analytics_snapshots

Daily metric aggregates per platform.

workspace_id, social_account_id, metric, value, date

All tables enforce Row Level Security keyed on workspace_id. API responses expose IDs you can reference safely.

Scheduling Lifecycle

Draft: Posts start in status = 'draft' with optional scheduled time.

Scheduled: When publish time is set, the post enters the scheduling queue.

Queued: Five minutes before publish, the scheduler locks the record and prepares payloads for each platform.

Publishing: The scheduler sends payloads to the respective social APIs. Failures trigger retries with exponential backoff (up to 3 attempts).

Published: On success, status = 'published' and published_at stores the actual timestamp per platform.

Failed: After retries, failures are marked with error codes accessible via /posts/{id}/deliveries.

Use webhooks (post.scheduled, post.published, post.failed) to stay synchronized with these transitions.

Conflict Avoidance

Updating a post within 5 minutes of publishing locks the record to prevent conflicting changes. The API returns 409 conflict if you attempt to edit during this window.

Media assets referenced by scheduled posts cannot be deleted until the post publishes or is cancelled.

Cancelling a post removes it from the queue immediately and emits a post.cancelled webhook.

Integrating Safely

Always fetch the latest post representation before editing to avoid overwriting teammate changes.

Use idempotency keys (Idempotency-Key header) when creating posts to prevent duplicates.

When syncing reviews, use the cursor parameter to fetch only new items since your last sync.

To explore authentication requirements for these operations, revisit Authentication & OAuth. For event-driven updates, pair this guide with Webhooks & Events.