documentation/content/en/methods/statuses.md

---
title: statuses API methods
description: Publish, interact, and view information about statuses.
menu:
  docs:
    weight: 30
    name: statuses
    parent: methods
    identifier: methods-statuses
aliases: [
  "/methods/statuses",
  "/api/methods/statuses",
]
---

<style>
#TableOfContents ul ul ul {display: none}
</style>

## Publish new status {#create}

```http
POST https://mastodon.example/api/v1/statuses HTTP/1.1
```

Post a new status.

**Returns:** [Status]({{<relref "entities/status">}}). When `scheduled_at` is present, [ScheduledStatus]({{<relref "entities/scheduledstatus">}}) is returned instead.\
**OAuth:** User + `write:statuses`\
**Version history:**\
0.0.0 - added\
2.7.0 - `scheduled_at` added\
2.8.0 - `poll` added

#### Request

##### Headers

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

Idempotency-Key
: Provide this header with any arbitrary string to prevent duplicate submissions of the same status. Consider using a hash or UUID generated client-side. Idempotency keys are stored for up to 1 hour.

##### Form data parameters

status
: {{<required>}} String. The text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided.

media_ids[]
: {{<required>}} Array of String. Include Attachment IDs to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used.

poll[options][]
: {{<required>}} Array of String. Possible answers to the poll. If provided, `media_ids` cannot be used, and `poll[expires_in]` must be provided.

poll[expires_in]
: {{<required>}} Integer. Duration that the poll should be open, in seconds. If provided, `media_ids` cannot be used, and `poll[options]` must be provided.

poll[multiple]
: Boolean. Allow multiple choices? Defaults to false.

poll[hide_totals]
: Boolean. Hide vote counts until the poll ends? Defaults to false.

in_reply_to_id
: String. ID of the status being replied to, if status is a reply.

sensitive
: Boolean. Mark status and attached media as sensitive? Defaults to false.

spoiler_text
: String. Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field.

visibility
: String. Sets the visibility of the posted status to `public`, `unlisted`, `private`, `direct`.

language
: String. ISO 639 language code for this status.

scheduled_at
: String. ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.

#### Response
##### 200: OK

Status will be posted with chosen parameters:

```json
{
  "id": "103254962155278888",
  "created_at": "2019-12-05T11:34:47.196Z",
  // ...
  "content": "<p>test content</p>",
  // ...
  "application": {
    "name": "test app",
    "website": null
  },
  // ...
}
```

If scheduled_at is provided, then a ScheduledStatus will be returned instead:

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

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 422: Unprocessable entity

```json
{
  "error": "Validation failed: Text can't be blank"
}
```

---

## View a single status {#get}

```http
GET https://mastodon.example/api/v1/statuses/:id HTTP/1.1
```

Obtain information about a status.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\
**Version history:**\
0.0.0 - added\
2.7.0 - public statuses no longer require token

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.

#### Response
##### 200: OK

```json
{
  "id": "1",
  "created_at": "2016-03-16T14:44:31.580Z",
  "in_reply_to_id": null,
  "in_reply_to_account_id": null,
  "sensitive": false,
  "spoiler_text": "",
  "visibility": "public",
  "language": "en",
  "uri": "https://mastodon.social/users/Gargron/statuses/1",
  "url": "https://mastodon.social/@Gargron/1",
  "replies_count": 7,
  "reblogs_count": 98,
  "favourites_count": 112,
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "content": "<p>Hello world</p>",
  "reblog": null,
  "application": null,
  "account": {
    "id": "1",
    "username": "Gargron",
    "acct": "Gargron",
    "display_name": "Eugen",
    "locked": false,
    "bot": false,
    "created_at": "2016-03-16T14:34:26.392Z",
    "note": "<p>Developer of Mastodon and administrator of mastodon.social. I post service announcements, development updates, and personal stuff.</p>",
    "url": "https://mastodon.social/@Gargron",
    "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
    "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/d96d39a0abb45b92.jpg",
    "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
    "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/c91b871f294ea63e.png",
    "followers_count": 320472,
    "following_count": 453,
    "statuses_count": 61163,
    "last_status_at": "2019-12-05T03:03:02.595Z",
    "emojis": [],
    "fields": [
      {
        "name": "Patreon",
        "value": "<a href=\"https://www.patreon.com/mastodon\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
        "verified_at": null
      },
      {
        "name": "Homepage",
        "value": "<a href=\"https://zeonfederated.com\" rel=\"me nofollow noopener noreferrer\" target=\"_blank\"><span class=\"invisible\">https://</span><span class=\"\">zeonfederated.com</span><span class=\"invisible\"></span></a>",
        "verified_at": "2019-07-15T18:29:57.191+00:00"
      }
    ]
  },
  "media_attachments": [],
  "mentions": [],
  "tags": [],
  "emojis": [],
  "card": null,
  "poll": null
}
```

##### 401: Unauthorized

Instance is in authorized-fetch mode.

```json
{
  "error": "This API requires an authenticated user"
}
```

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

---

## Delete a status {#delete}

```http
DELETE https://mastodon.example/api/v1/statuses/:id HTTP/1.1
```

Delete one of your own statuses.

**Returns:** [Status]({{< relref "entities/status" >}}) with source `text` and `poll` or `media_attachments`\
**OAuth:** User token + `write:statuses`\
**Version history:**\
0.0.0 - added\
2.9.0 - return source properties, for use with delete and redraft

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Note the special properties `text` and `poll` or `media_attachments` which may be used to repost the status, e.g. in case of delete-and-redraft functionality. With [POST /api/v1/statuses](#create), use `text` as the value for `status` parameter, `media_attachments[n]["id"]` for the `media_ids` array parameter, and `poll` properties with the corresponding parameters (e.g. `poll[multiple]` and `poll[options]`, with a new `poll[expires_in]` and `poll[hide_totals]` per user input.

Example of deleting a media post:

```json
{
  "id": "103254193998341330",
  "created_at": "2019-12-05T08:19:26.052Z",
  "in_reply_to_id": null,
  "in_reply_to_account_id": null,
  "sensitive": false,
  "spoiler_text": "",
  "visibility": "public",
  "language": "en",
  "uri": "https://mastodon.social/users/trwnh/statuses/103254193998341330",
  "url": "https://mastodon.social/@trwnh/103254193998341330",
  "replies_count": 0,
  "reblogs_count": 0,
  "favourites_count": 0,
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  "text": "test",
  "reblog": null,
  "application": {
    "name": "Web",
    "website": null
  },
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    "display_name": "infinite love ⴳ",
    // ...
  },
  "media_attachments": [
    {
      "id": "22345792",
      "type": "image",
      "url": "https://files.mastodon.social/media_attachments/files/022/345/792/original/57859aede991da25.jpeg",
      "preview_url": "https://files.mastodon.social/media_attachments/files/022/345/792/small/57859aede991da25.jpeg",
      "remote_url": null,
      "text_url": "https://mastodon.social/media/2N4uvkuUtPVrkZGysms",
      "meta": {
        "original": {
          "width": 640,
          "height": 480,
          "size": "640x480",
          "aspect": 1.3333333333333333
        },
        "small": {
          "width": 461,
          "height": 346,
          "size": "461x346",
          "aspect": 1.3323699421965318
        },
        "focus": {
          "x": -0.27,
          "y": 0.51
        }
      },
      "description": "test media description",
      "blurhash": "UFBWY:8_0Jxv4mx]t8t64.%M-:IUWGWAt6M}"
    }
  ],
  "mentions": [],
  "tags": [],
  "emojis": [],
  "card": null,
  "poll": null
}
```

Example of deleting a poll:

```json
{
  "id": "103254222827484720",
  "created_at": "2019-12-05T08:26:45.958Z",
  "in_reply_to_id": null,
  "in_reply_to_account_id": null,
  "sensitive": false,
  "spoiler_text": "",
  "visibility": "public",
  "language": "en",
  "uri": "https://mastodon.social/users/trwnh/statuses/103254222827484720",
  "url": "https://mastodon.social/@trwnh/103254222827484720",
  "replies_count": 0,
  "reblogs_count": 0,
  "favourites_count": 0,
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  "text": "test",
  "reblog": null,
  "application": {
    "name": "Web",
    "website": null
  },
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    "display_name": "infinite love ⴳ",
    // ...
  },
  "media_attachments": [],
  "mentions": [],
  "tags": [],
  "emojis": [],
  "card": null,
  "poll": {
    "id": "34858",
    "expires_at": "2019-12-06T08:26:45.945Z",
    "expired": false,
    "multiple": false,
    "votes_count": 1,
    "voters_count": 1,
    "voted": true,
    "own_votes": [],
    "options": [
      {
        "title": "test 1",
        "votes_count": 1
      },
      {
        "title": "test 2",
        "votes_count": 0
      }
    ],
    "emojis": []
  }
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status is not owned by you or does not exist

```json
{
  "error": "Record not found"
}
```

---

## Get parent and child statuses in context {#context}

```http
GET https://mastodon.example/api/v1/statuses/:id/context HTTP/1.1
```

View statuses above and below this status in the thread.

**Returns:** [Context]({{< relref "entities/context" >}})\
**OAuth:** Public for public statuses. User token + `read:statuses` for private statuses.\
**Version history:**\
0.0.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.

#### Response
##### 200: OK

```json
{
  "ancestors": [
    {
      "id": "103188938570975982",
      "created_at": "2019-11-23T19:44:00.124Z",
      "in_reply_to_id": null,
      "in_reply_to_account_id": null,
      // ...
    },
    {
      "id": "103188971072973252",
      "created_at": "2019-11-23T19:52:23.398Z",
      "in_reply_to_id": "103188938570975982",
      "in_reply_to_account_id": "634458",
      // ...
    },
    {
      "id": "103188982235527758",
      "created_at": "2019-11-23T19:55:08.208Z",
      "in_reply_to_id": "103188971072973252",
      "in_reply_to_account_id": "14715",
      // ...
    }
  ],
  "descendants": [
    {
      "id": "103189026958574542",
      "created_at": "2019-11-23T20:06:36.011Z",
      "in_reply_to_id": "103189005915505698",
      "in_reply_to_account_id": "634458",
      // ...
    }
  ]
}
```

##### 404: Not found

Status is private or does not exist

```json
{
  "error": "Record not found"
}
```

---

## See who boosted a status {#reblogged_by}

```http
GET https://mastodon.example/api/v1/statuses/:id/reblogged_by HTTP/1.1
```

View who boosted a given status.

**Returns:** Array of [Account]({{< relref "entities/account" >}})\
**OAuth:** Public for public statuses. User token + `read:statuses` for private statuses.
**Version history:**\
0.0.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.

#### Response
##### 200: OK

A list of statuses that boosted the status

```json
[
  {
    "id": "711345",
    "username": "Norman_Doors",
    "acct": "Norman_Doors@witches.live",
    // ...
  },
  // ...
]
```

##### 404: Not found

Status does not exist or is private

```json
{
  "error": "Record not found"
}
```

---

## See who favourited a status {#favourited_by}

```http
GET https://mastodon.example/api/v1/statuses/:id/favourited_by HTTP/1.1
```

View who favourited a given status.

**Returns:** Array of [Account]({{< relref "entities/account" >}})\
**OAuth:** Public for public statuses. User token + `read:statuses` for private statuses.\
**Version history:**\
0.0.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.

#### Response
##### 200: OK

A list of accounts who favourited the status

```json
[
  {
    "id": "828600",
    "username": "fructose_dealer",
    "acct": "fructose_dealer@radical.town",
    // ...
  },
  // ...
]
```

##### 404: Not found

Status does not exist or is private

```json
{
  "error": "Record not found"
}
```

---

## Favourite a status {#favourite}

```http
POST https://mastodon.example/api/v1/statuses/:id/favourite HTTP/1.1
```

Add a status to your favourites list.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:favourites`\
**Version history:**\
0.0.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Status favourited or was already favourited

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": true,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private

```json
{
  "error": "Record not found"
}
```

---

## Undo favourite of a status {#unfavourite}

```http
POST https://mastodon.example/api/v1/statuses/:id/unfavourite HTTP/1.1
```

Remove a status from your favourites list.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:favourites`\
**Version history:**\
0.0.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Status unfavourited or was already not favourited

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private

```json
{
  "error": "Record not found"
}
```

---

## Boost a status {#boost}

```http
POST https://mastodon.example/api/v1/statuses/:id/reblog HTTP/1.1
```

Reshare a status on your own profile.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:statuses`\
**Version history:**\
0.0.0 - added\
2.8.0 - add `visibility` parameter

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

##### Form data parameters

visibility
: String. Any visibility except `limited` or `direct` (i.e. `public`, `unlisted`, `private`). Defaults to public. Currently unused in UI.

#### Response
##### 200: OK

Status has been reblogged. Note that the top-level id has changed. The id of the boosted status is now inside the `reblog` property. The top-level id is the id of the reblog itself. Also note that reblogs cannot be pinned.

```json
{
  "id": "103254401326800919",
  "created_at": "2019-12-05T09:12:09.625Z",
  // ...
  "favourited": false,
  "reblogged": true,
  "muted": false,
  "bookmarked": false,
  // ...
  "reblog": {
    "id": "99734435964706331",
    "created_at": "2018-03-23T17:38:40.700Z",
    // ...
    "favourited": false,
    "reblogged": true,
    "muted": false,
    "bookmarked": false,
    "pinned": false,
    // ...
  },
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private

```json
{
  "error": "Record not found"
}
```

---

## Undo boost of a status {#unreblog}

```http
POST https://mastodon.example/api/v1/statuses/:id/unreblog HTTP/1.1
```

Undo a reshare of a status.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:statuses`\
**Version history:**\
0.0.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Status unboosted or was already not boosted

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private

```json
{
  "error": "Record not found"
}
```

---

## Bookmark a status {#bookmark}

```http
POST https://mastodon.example/api/v1/statuses/:id/bookmark HTTP/1.1
```

Privately bookmark a status.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:bookmarks`\
**Version history:**\
3.1.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Status bookmarked or was already bookmarked

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": true,
  "pinned": false,
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

---

## Undo bookmark of a status {#unbookmark}

```http
POST https://mastodon.example/api/v1/statuses/:id/unbookmark HTTP/1.1
```

Remove a status from your private bookmarks.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:bookmarks`\
**Version history:**\
3.1.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Status was unbookmarked or was already not bookmarked

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

---

## Mute a conversation {#mute}

```http
POST https://mastodon.example/api/v1/statuses/:id/mute HTTP/1.1
```

Do not receive notifications for the thread that this status is part of. Must be a thread in which you are a participant.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:mutes`\
**Version history:**\
1.4.2 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Status's conversation muted, or was already muted

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": false,
  "reblogged": false,
  "muted": true,
  "bookmarked": false,
  "pinned": false,
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

---

## Unmute a conversation {#unmute}

```http
POST https://mastodon.example/api/v1/statuses/:id/unmute HTTP/1.1
```

Start receiving notifications again for the thread that this status is part of.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:mutes`\
**Version history:**\
1.4.2 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Status's conversation unmuted, or was already unmuted

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

---

## Pin status to profile {#pin}

```http
POST https://mastodon.example/api/v1/statuses/:id/pin HTTP/1.1
```

Feature one of your own public statuses at the top of your profile.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:accounts`\
**Version history:**\
1.6.0 - added\
3.5.0 - you can now pin private posts

#### Request

##### Path parameters

:id
: {{<required>}} String. The local ID of the Status in the database. The status should be authored by the authorized account.

##### Headers

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

#### Response
##### 200: OK

Status pinned. Note the status is not a reblog and its authoring account is your own.

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": true,
  // ...
  "reblog": null,
  // ...
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    // ...
  },
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

##### 422: Unprocessable entity

Status is not owned by you:

```json
{
  "error": "Validation failed: Someone else's post cannot be pinned"
}
```

Prior to 3.5.0, you could not pin one of your private statuses because private statuses could not be fetched from remote sites, and must have been delivered. (3.5.0 added a mechanism to fetch statuses on behalf of an account.)

```json
{
  "error": "Validation failed: Non-public toot cannot be pinned"
}
```

---

## Unpin status from profile {#unpin}

```http
POST https://mastodon.example/api/v1/statuses/:id/unpin HTTP/1.1
```

Unfeature a status from the top of your profile.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:accounts`\
**Version history:**\
1.6.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The local ID of the Status in the database.

##### Headers

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

#### Response
##### 200: OK

Status unpinned, or was already not pinned

```json
{
  "id": "99734435964706331",
  "created_at": "2018-03-23T17:38:40.700Z",
  // ...
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  // ...
  "reblog": null,
  // ...
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    // ...
  },
  // ...
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

---

## Edit a status {#edit}

```http
PUT https://mastodon.example/api/v1/statuses/:id HTTP/1.1
```

Edit a given status to change its text, sensitivity, media attachments, or poll. Note that editing a poll's options will reset the votes.

**Returns:** [Status]({{< relref "entities/status" >}})\
**OAuth:** User token + `write:statuses`\
**Version history:**\
3.5.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The ID of the SOMETHING in the database.

##### Headers

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

##### Form data parameters

status
: String. The plain text content of the status.

spoiler_text
: String. The plain text subject or content warning of the status.

sensitive
: Boolean. Whether the status should be marked as sensitive.

media_ids[]
: Array of String. Include Attachment IDs to be attached as media. If provided, `status` becomes optional, and `poll` cannot be used.

poll[options][]
: Array of String. Possible answers to the poll. If provided, `media_ids` cannot be used, and `poll[expires_in]` must be provided.

poll[expires_in]
: Integer. Duration that the poll should be open, in seconds. If provided, `media_ids` cannot be used, and `poll[options]` must be provided.

poll[multiple]
: Boolean. Allow multiple choices? Defaults to false.

poll[hide_totals]
: Boolean. Hide vote counts until the poll ends? Defaults to false.

#### Response
##### 200: OK

Status has been successfully edited.

```json
{
  "id": "108942703571991143",
  "created_at": "2022-09-04T23:22:13.704Z",
  "in_reply_to_id": null,
  "in_reply_to_account_id": null,
  "sensitive": false,
  "spoiler_text": "",
  "visibility": "public",
  "language": "en",
  "uri": "https://mastodon.social/users/trwnh/statuses/108942703571991143",
  "url": "https://mastodon.social/@trwnh/108942703571991143",
  "replies_count": 3,
  "reblogs_count": 1,
  "favourites_count": 6,
  "edited_at": "2022-09-05T00:33:20.309Z",
  "favourited": false,
  "reblogged": false,
  "muted": false,
  "bookmarked": false,
  "pinned": false,
  "content": "<p>this is a status that has been edited multiple times to change the text, add a poll, and change poll options.</p>",
  "filtered": [],
  "reblog": null,
  "application": {
    "name": "SubwayTooter",
    "website": null
  },
  "account": {
    "id": "14715",
    "username": "trwnh",
    "acct": "trwnh",
    "display_name": "infinite love ⴳ",
    // ...
  },
  "media_attachments": [],
  "mentions": [],
  "tags": [],
  "emojis": [],
  "card": null,
  "poll": null
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist, is private, or is not owned by you.

```json
{
  "error": "Record not found"
}
```

##### 422: Unprocessable entity

```json
{
  "error": "Validation failed: Text can't be blank"
}
```

---

## View edit history of a status {#history}

```http
GET https://mastodon.example/api/v1/statuses/:id/history HTTP/1.1
```

Get all known versions of a status, including the initial and current states.

**Returns:** Array of [StatusEdit]({{< relref "entities/statusedit" >}})\
**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\
**Version history:**\
3.5.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The local ID of the Status in the database.

##### Headers

Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.

#### Response
##### 200: OK

```json
[
  {
    "content": "<p>this is a status that will be edited</p>",
    "spoiler_text": "",
    "sensitive": false,
    "created_at": "2022-09-04T23:22:13.704Z",
    "account": {
      "id": "14715",
      "username": "trwnh",
      "acct": "trwnh",
      "display_name": "infinite love ⴳ",
      // ...
    },
    "media_attachments": [],
    "emojis": []
  },
  {
    "content": "<p>this is a status that has been edited</p>",
    "spoiler_text": "",
    "sensitive": false,
    "created_at": "2022-09-04T23:22:42.555Z",
    "account": {
      "id": "14715",
      "username": "trwnh",
      "acct": "trwnh",
      "display_name": "infinite love ⴳ",
      // ...
    },
    "media_attachments": [],
    "emojis": []
  },
  {
    "content": "<p>this is a status that has been edited twice</p>",
    "spoiler_text": "",
    "sensitive": false,
    "created_at": "2022-09-04T23:22:55.956Z",
    "account": {
      "id": "14715",
      "username": "trwnh",
      "acct": "trwnh",
      "display_name": "infinite love ⴳ",
      // ...
    },
    "media_attachments": [],
    "emojis": []
  },
  {
    "content": "<p>this is a status that has been edited three times. this time a poll has been added.</p>",
    "spoiler_text": "",
    "sensitive": false,
    "created_at": "2022-09-05T00:01:48.160Z",
    "poll": {
      "options": [
        {
          "title": "cool"
        },
        {
          "title": "uncool"
        },
        {
          "title": "spiderman"
        }
      ]
    },
    "account": {
      "id": "14715",
      "username": "trwnh",
      "acct": "trwnh",
      "display_name": "infinite love ⴳ",
      // ...
    },
    "media_attachments": [],
    "emojis": []
  },
  {
    "content": "<p>this is a status that has been edited three times. this time a poll has been added.</p>",
    "spoiler_text": "",
    "sensitive": false,
    "created_at": "2022-09-05T00:03:32.480Z",
    "poll": {
      "options": [
        {
          "title": "cool"
        },
        {
          "title": "uncool"
        },
        {
          "title": "spiderman (this option has been changed)"
        }
      ]
    },
    "account": {
      "id": "14715",
      "username": "trwnh",
      "acct": "trwnh",
      "display_name": "infinite love ⴳ",
      // ...
    },
    "media_attachments": [],
    "emojis": []
  }
]
```

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

---

## View status source {#source}

```http
GET https://mastodon.example/api/v1/statuses/:id/source HTTP/1.1
```

Obtain the source properties for a status so that it can be edited.

**Returns:** [StatusSource]({{< relref "entities/statussource" >}})\
**OAuth:** App token + `read:statuses`\
**Version history:**\
3.5.0 - added

#### Request

##### Path parameters

:id
: {{<required>}} String. The local ID of the Status in the database.

##### Headers

Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.

#### Response
##### 200: OK

```json
{
  "id": "108942703571991143",
  "text": "this is a status that will be edited",
  "spoiler_text": ""
}
```

##### 401: Unauthorized

Invalid or missing Authorization header.

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

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

---

## (DEPRECATED) Fetch preview card {#card}

```http
GET https://mastodon.example/api/v1/statuses/:id/card HTTP/1.1
```

**Returns:** [PreviewCard]({{< relref "entities/PreviewCard" >}})\
**OAuth:** Public for public statuses, user token + `read:statuses` for private statuses\
**Version history:**\
0.0.0 - added\
2.6.0 - deprecated in favor of card property inlined on Status entity\
3.0.0 - removed

#### Request

##### Path parameters

:id
: {{<required>}} String. The local ID of the Status in the database.

##### Headers

Authorization
: Provide this header with `Bearer <user token>` to gain authorized access to this API method.

#### Response
##### 200: OK

```json
{
  "url": "https://www.youtube.com/watch?v=OMv_EPMED8Y",
  "title": "♪ Brand New Friend (Christmas Song!)",
  "description": "",
  "type": "video",
  "author_name": "YOGSCAST Lewis & Simon",
  "author_url": "https://www.youtube.com/user/BlueXephos",
  "provider_name": "YouTube",
  "provider_url": "https://www.youtube.com/",
  "html": "<iframe width=\"480\" height=\"270\" src=\"https://www.youtube.com/embed/OMv_EPMED8Y?feature=oembed\" frameborder=\"0\" allowfullscreen=\"\"></iframe>",
  "width": 480,
  "height": 270,
  "image": "https://files.mastodon.social/preview_cards/images/014/179/145/original/9cf4b7cf5567b569.jpeg",
  "embed_url": ""
}
```

##### 404: Not found

Status does not exist or is private.

```json
{
  "error": "Record not found"
}
```

---

## See also

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

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

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

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

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

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

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

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

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

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