documentation/content/en/methods/scheduled_statuses.md

title	description	menu	aliases
scheduled_statuses API methods	Manage statuses that were scheduled to be published at a future date.	docs weight name parent identifier 30 scheduled_statuses methods-statuses methods-scheduled_statuses	/methods/scheduled_statuses /api/methods/scheduled_statuses /methods/statuses/scheduled_statuses

View scheduled statuses

GET https://mastodon.example/api/v1/scheduled_statuses HTTP/1.1

Returns: Array of [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})
OAuth: User token + read:statuses
Version history:
2.7.0 - added
3.3.0 - both min_id and max_id can be used at the same time now

Request

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Query parameters

max_id

String. Return results older than ID.

since_id

String. Return results newer than ID.

min_id

String. Return results immediately newer than ID.

limit

Integer. Maximum number of results to return. Defaults to 20. Max 40.

Response

200: OK

[
  {
    "id": "3221",
    "scheduled_at": "2019-12-05T12:33:01.000Z",
    "params": {
      "poll": null,
      "text": "test content",
      "media_ids": null,
      "sensitive": null,
      "visibility": null,
      "idempotency": null,
      "scheduled_at": null,
      "spoiler_text": null,
      "application_id": 596551,
      "in_reply_to_id": null
    },
    "media_attachments": []
  }
]

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

View a single scheduled status

GET https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1

Returns: [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})
OAuth: User token + read:statuses
Version history:
2.7.0 - added

Request

Path parameters

:id

{{}} String. The ID of the ScheduledStatus in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

{
  "id": "3221",
  "scheduled_at": "2019-12-05T12:33:01.000Z",
  "params": {
    "poll": null,
    "text": "test content",
    "media_ids": null,
    "sensitive": null,
    "visibility": null,
    "idempotency": null,
    "scheduled_at": null,
    "spoiler_text": null,
    "application_id": 596551,
    "in_reply_to_id": null
  },
  "media_attachments": []
}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

404: Not found

ScheduledStatus is not owned by you or does not exist

{
  "error": "Record not found"
}

---

Update a scheduled status's publishing date

PUT https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1

Returns: [ScheduledStatus]({{< relref "entities/scheduledstatus" >}})
OAuth: User token + write:statuses
Version history:
2.7.0 - added

Request

Path parameters

:id

{{}} String. The ID of the SOMETHING in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Form data parameters

scheduled_at

String. ISO 8601 Datetime at which the status will be published. Must be at least 5 minutes into the future.

Response

200: OK

{
  "id": "3221",
  "scheduled_at": "2019-12-05T13:33:01.000Z",
  "params": {
    "poll": null,
    "text": "test content",
    "media_ids": null,
    "sensitive": null,
    "visibility": null,
    "idempotency": null,
    "scheduled_at": null,
    "spoiler_text": null,
    "application_id": 596551,
    "in_reply_to_id": null
  },
  "media_attachments": []
}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

404: Not found

ScheduledStatus is not owned by you or does not exist

{
  "error": "Record not found"
}

422: Unprocessable entity

{
  "error": "Validation failed: Scheduled at The scheduled date must be in the future"
}

---

Cancel a scheduled status

DELETE https://mastodon.example/api/v1/scheduled_statuses/:id HTTP/1.1

Returns: empty object
OAuth: User token + write:statuses
Version history:
2.7.0 - added

Request

Path parameters

:id

{{}} String. The ID of the SOMETHING in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

{}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

404: Not found

ScheduledStatus is not owned by you or does not exist

{
  "error": "Record not found"
}

---

See also

{{< page-relref ref="methods/statuses#create" caption="POST /api/v1/statuses (scheduled_at parameter)" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/scheduled_statuses_controller.rb" caption="app/controllers/api/v1/scheduled_statuses_controller.rb" >}}