---
title: "List Schedules"
method: GET
path: "/v1/schedules"
tags: ["Schedules"]
---

# List Schedules

`GET /v1/schedules`

## Request

- Base URL: `https://api.pinbridge.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pinbridge.io/v1/schedules`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

List schedules for the workspace, latest run_at first by default, with optional filters.

The `X-Total-Count` response header carries the number of schedules matching
the filters and search, so clients can page with `limit` and `offset`.

## Query parameters

- `limit` integer
- `offset` integer
- `q` string, nullable: Case-insensitive search across the pin title, description and link URL
- `sort` 'run_at_desc' | 'run_at_asc' | 'created_at_desc' | 'created_at_asc' | 'title_asc' | 'title_desc' | 'status_asc' | 'status_desc': Sort order; run_at_asc lists the next run first
- `account_id` string, uuid, nullable: Only schedules for this Pinterest account
- `board_id` string, nullable: Only schedules targeting this board
- `status` 'scheduled' | 'queued' | 'deferred' | 'running' | 'done' | 'failed' | 'canceled': Schedule status enum.
- `since` string, date-time, nullable: Only schedules running at or after this ISO 8601 timestamp
- `until` string, date-time, nullable: Only schedules running before this ISO 8601 timestamp

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Response `200`

Successful Response

- ScheduleResponse[]
  - `id` string, uuid, required
  - `workspace_id` string, uuid, required
  - `pinterest_account_id` string, uuid, required
  - `run_at` string, date-time, required
  - `status` 'scheduled' | 'queued' | 'deferred' | 'running' | 'done' | 'failed' | 'canceled', required: Schedule status enum.
  - `payload` object, required
  - `last_error` string, nullable
  - `pin_id` string, uuid, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `warnings` ScheduleWarning[]: Set when creating or rescheduling: quota_may_be_exceeded means the schedule's month already has as many pins published or scheduled as the plan includes, so this pin may not publish.
    - `code` string, required: Stable warning code, e.g. quota_may_be_exceeded
    - `message` string, required
    - `remediation` string, nullable
    - `limit_type` string, nullable
    - `plan` string, nullable
    - `plan_name` string, nullable
    - `limit` integer, nullable
    - `used` integer, nullable: Pins already published or scheduled in the schedule's month
    - `recommended_plan` string, nullable
    - `recommended_plan_name` string, nullable
    - `recommended_limit` integer, nullable
    - `upgrade_url` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/pinbridge/apis/pinbridge-api.md) · [All operations](https://skmtc.dev/pinbridge/apis/pinbridge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pinbridge/apis/pinbridge-api/revisions/b17603589d01?raw)