> For the complete documentation index, see [llms.txt](https://mastodon.gitbook.io/mastodon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mastodon.gitbook.io/mastodon/jp/methods/statuses/polls.md).

# polls

## View a poll

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/polls/:id`

**Returns:** Poll\
**OAuth:** Public if parent status is public. User token + `read:statuses` if parent status is private.\
**Version history:**\
2.8.0 - added

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| :id  | string | ID of the poll in the database |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "34830",
  "expires_at": "2019-12-05T04:05:08.302Z",
  "expired": true,
  "multiple": false,
  "votes_count": 10,
  "voters_count": null,
  "voted": true,
  "own_votes": [
    1
  ],
  "options": [
    {
      "title": "accept",
      "votes_count": 6
    },
    {
      "title": "deny",
      "votes_count": 4
    }
  ],
  "emojis": []
}
```

{% endtab %}

{% tab title="404 Poll does not exist, or poll's parent status is private" %}

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

{% endtab %}
{% endtabs %}

## Vote on a poll

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/polls/:id/votes`

**Returns:** Poll\
**OAuth:** User token + `write:statuses`\
**Version history:**\
2.8.0 - added

#### Path Parameters

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| :id  | string | ID of the poll in the database |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name       | Type  | Description                                                           |
| ---------- | ----- | --------------------------------------------------------------------- |
| choices\[] | array | Array of own votes containing index for each option (starting from 0) |

{% tabs %}
{% tab title="200 Poll was voted on" %}

```javascript
{
  "id": "34873",
  "expires_at": "2019-12-05T11:16:17.426Z",
  "expired": false,
  "multiple": true,
  "votes_count": 5,
  "voters_count": null,
  "voted": true,
  "own_votes": [
    0,
    2,
    4,
    9,
    6
  ],
  "options": [
    {
      "title": "option 0",
      "votes_count": 1
    },
    {
      "title": "option 1",
      "votes_count": 0
    },
    {
      "title": "option 2",
      "votes_count": 1
    },
    {
      "title": "option 3",
      "votes_count": 0
    },
    {
      "title": "option 4",
      "votes_count": 1
    },
    {
      "title": "option 5",
      "votes_count": 0
    },
    {
      "title": "option 6",
      "votes_count": 1
    },
    {
      "title": "option 7",
      "votes_count": 0
    },
    {
      "title": "option 8",
      "votes_count": 0
    },
    {
      "title": "option 9",
      "votes_count": 1
    }
  ],
  "emojis": []
}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

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

{% endtab %}

{% tab title="404 Poll does not exist, or poll's parent status is private" %}

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

{% endtab %}

{% tab title="422 Already voted or poll is expired" %}
{% tabs %}
{% tab title="already voted" %}

```javascript
{
  "error": "Validation failed: You have already voted on this poll"
}
```

{% endtab %}

{% tab title="expired" %}

```javascript
{
  "error": "Validation failed: The poll has already ended"
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}