Queues API

The queue system lets you define recurring time slots for a brand. Posts added to a queue automatically fill the next available slot — no need to calculate dates yourself. Especially useful for AI agents and content automation pipelines.

Using a standard API key? You don't need to create a queue through the API. Set your posting times once under Settings → Queue Settings in the dashboard, then pass "queue": true when you create a post. It goes into the same slot Add to Queue would pick in the dashboard. The queue endpoints on this page are for API Profiles, which partner keys create.

How queues work

1

Create queue slots for a brand

Define which days and times posts should go out (e.g., Monday 9am, Wednesday 2pm, Friday 10am)

2

Add posts to the queue

When creating a post, pass "queue": true instead of scheduledFor

3

Posts auto-fill the next available slot

Each post is assigned the next open time slot. Slots cycle weekly — once all slots for a week are filled, the queue rolls into the next week.

Endpoints

POST/api/v1/queuesCreate queue slots
GET/api/v1/queuesList queue configurations
GET/api/v1/queues/:id/nextPreview upcoming slots
PATCH/api/v1/queues/:idUpdate queue slots or timezone
DELETE/api/v1/queues/:idDelete a queue

Create queue slots

POST/api/v1/queuesCreate a new queue configuration for a brand

Each brand can have one queue. Creating a second queue for the same brand returns a 409 queue_exists error; use PATCH to change an existing queue.

Request Body

brandId
stringRequired

The API Profile ID to create the queue for (from POST /api/v1/profiles). Dashboard workspace IDs aren't accepted.

timezone
stringRequired

IANA timezone for slot scheduling (e.g., America/Toronto, Europe/London)

slots
arrayRequired

Array of slot objects, each with a day and times array

slots[].day
stringRequired

Day of the week

mondaytuesdaywednesdaythursdayfridaysaturdaysunday
slots[].times
string[]Required

Array of times in 24-hour format (e.g., "09:00", "14:30")

curl -X POST https://schedulala.com/api/v1/queues \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "brand_xyz789",
    "timezone": "America/Toronto",
    "slots": [
      { "day": "monday", "times": ["09:00", "14:00"] },
      { "day": "tuesday", "times": ["09:00", "14:00"] },
      { "day": "wednesday", "times": ["09:00", "14:00"] },
      { "day": "thursday", "times": ["09:00", "14:00"] },
      { "day": "friday", "times": ["09:00", "14:00"] }
    ]
  }'
{
  "success": true,
  "queue": {
    "id": "queue_abc123",
    "brandId": "brand_xyz789",
    "timezone": "America/Toronto",
    "slots": [
      {
        "day": "monday",
        "times": [
          "09:00",
          "14:00"
        ]
      },
      {
        "day": "tuesday",
        "times": [
          "09:00",
          "14:00"
        ]
      },
      {
        "day": "wednesday",
        "times": [
          "09:00",
          "14:00"
        ]
      },
      {
        "day": "thursday",
        "times": [
          "09:00",
          "14:00"
        ]
      },
      {
        "day": "friday",
        "times": [
          "09:00",
          "14:00"
        ]
      }
    ],
    "totalSlotsPerWeek": 10,
    "isActive": true,
    "createdAt": "2026-03-01T12:00:00.000Z"
  }
}

List queue configurations

GET/api/v1/queuesList all queue configurations for your account

Lists queues created through this API. Your dashboard Queue Settings aren't listed here, but "queue": true still uses them on a standard key.

Query Parameters

brandId
stringOptional

Filter queues by API Profile ID

curl https://schedulala.com/api/v1/queues?brandId=brand_xyz789 \
  -H "Authorization: Bearer sk_live_abc123xyz789..."
{
  "success": true,
  "queues": [
    {
      "id": "queue_abc123",
      "brandId": "brand_xyz789",
      "timezone": "America/Toronto",
      "slots": [
        {
          "day": "monday",
          "times": [
            "09:00",
            "14:00"
          ]
        },
        {
          "day": "wednesday",
          "times": [
            "09:00",
            "14:00"
          ]
        },
        {
          "day": "friday",
          "times": [
            "09:00",
            "14:00"
          ]
        }
      ],
      "totalSlotsPerWeek": 6,
      "isActive": true,
      "pendingPosts": 3,
      "nextSlot": "2026-03-03T14:00:00.000Z",
      "createdAt": "2026-02-15T10:00:00.000Z"
    }
  ]
}

Preview upcoming slots

GET/api/v1/queues/:id/nextPreview the next upcoming time slots and which posts fill them

Query Parameters

count
numberOptional

Number of upcoming slots to return (max 50)

Default: 10

curl https://schedulala.com/api/v1/queues/queue_abc123/next?count=5 \
  -H "Authorization: Bearer sk_live_abc123xyz789..."
{
  "success": true,
  "queueId": "queue_abc123",
  "timezone": "America/Toronto",
  "upcoming": [
    {
      "datetime": "2026-03-03T14:00:00.000Z",
      "day": "monday",
      "time": "14:00",
      "post": {
        "id": "post_def456",
        "caption": "Queued post about productivity tips...",
        "status": "scheduled",
        "platforms": [
          "twitter",
          "linkedin"
        ],
        "externalId": null
      }
    },
    {
      "datetime": "2026-03-05T09:00:00.000Z",
      "day": "wednesday",
      "time": "09:00",
      "post": null
    },
    {
      "datetime": "2026-03-05T14:00:00.000Z",
      "day": "wednesday",
      "time": "14:00",
      "post": null
    },
    {
      "datetime": "2026-03-07T09:00:00.000Z",
      "day": "friday",
      "time": "09:00",
      "post": null
    },
    {
      "datetime": "2026-03-07T14:00:00.000Z",
      "day": "friday",
      "time": "14:00",
      "post": null
    }
  ]
}

Slots with post: null are empty and available. The next post added to this queue will fill the earliest open slot.

Update queue

PATCH/api/v1/queues/:idUpdate queue slots or timezone

Request Body

slots
arrayOptional

New slot configuration (replaces all existing slots)

timezone
stringOptional

New IANA timezone for slot scheduling

curl -X PATCH https://schedulala.com/api/v1/queues/queue_abc123 \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "Europe/London",
    "slots": [
      { "day": "monday", "times": ["10:00", "15:00"] },
      { "day": "thursday", "times": ["10:00", "15:00"] }
    ]
  }'
{
  "success": true,
  "queue": {
    "id": "queue_abc123",
    "brandId": "brand_xyz789",
    "timezone": "Europe/London",
    "slots": [
      {
        "day": "monday",
        "times": [
          "10:00",
          "15:00"
        ]
      },
      {
        "day": "thursday",
        "times": [
          "10:00",
          "15:00"
        ]
      }
    ],
    "totalSlotsPerWeek": 4,
    "isActive": true,
    "createdAt": "2026-02-15T10:00:00.000Z",
    "updatedAt": "2026-03-01T14:00:00.000Z"
  },
  "orphanedPostsConverted": 0
}

Note: Updating slots replaces the entire slot configuration. Posts whose scheduled time still matches a slot in the new configuration keep their times. Posts whose slot no longer exists are converted to draft; the response reports how many in orphanedPostsConverted.

Delete queue

DELETE/api/v1/queues/:idDelete a queue configuration
curl -X DELETE https://schedulala.com/api/v1/queues/queue_abc123 \
  -H "Authorization: Bearer sk_live_abc123xyz789..."
{
  "success": true,
  "message": "Queue deleted",
  "postsConverted": 2
}

Important: Posts already assigned to future time slots from this queue will revert to draft status. They will not be published unless you reschedule them manually or assign them to a different queue.

Adding a post to a queue

To add a post to a queue, use the POST /api/v1/posts endpoint and pass "queue": true instead of scheduledFor. The post is assigned the next open slot, at least 5 minutes from now. The slot comes from:

  1. A queue created through this API on your key. If you have queues on more than one API Profile, pass brandId to pick one. A slot is open until another post from the same queue takes it.
  2. Otherwise, on a standard key, your dashboard Queue Settings. A slot is skipped when you already have a post scheduled near that time, the same way Add to Queue works in the dashboard.
  3. If neither exists, the request returns 400 validation_error. Partner keys only use API queues.

With a test key (sk_test_), posts are simulated and never fill a slot, so every queued test post gets the same next slot.

curl -X POST https://schedulala.com/api/v1/posts \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Automating my content pipeline with queues!",
    "platforms": [
      { "platform": "twitter", "accountId": "acc_tw_123" },
      { "platform": "linkedin", "accountId": "acc_li_456" }
    ],
    "queue": true
  }'
{
  "success": true,
  "post": {
    "id": "post_ghi789",
    "content": "Automating my content pipeline with queues!",
    "mediaItems": [],
    "mediaType": "none",
    "status": "scheduled",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "acc_tw_123",
        "status": "pending"
      },
      {
        "platform": "linkedin",
        "accountId": "acc_li_456",
        "status": "pending"
      }
    ],
    "scheduledFor": "2026-03-05T09:00:00.000Z",
    "timezone": null,
    "isApiPost": true,
    "brandId": "brand_xyz789",
    "externalId": null,
    "createdAt": "2026-03-01T18:30:00.000Z",
    "updatedAt": "2026-03-01T18:30:00.000Z"
  }
}

Tip: You can mix queued and directly scheduled posts. Use queue for regular content cadence and scheduledFor for time-sensitive posts that need to go out at an exact moment.

Related

Posts API — Create, schedule, and manage posts across platformsAccounts API — Manage connected social accounts and brandsSandbox Mode — Test queues without publishing to real platforms