# streaming

Your application can use a [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) endpoint to receive updates in real-time. Server-sent events is an incredibly simple transport method that relies entirely on chunked-encoding transfer, i.e. the HTTP connection is kept open and receives new data periodically.

Alternatively, a WebSocket connection can also be established.

## Server-sent events (HTTP) <a href="#server-sent-events-http" id="server-sent-events-http"></a>

### Endpoints <a href="#endpoints" id="endpoints"></a>

#### GET /api/v1/streaming/health <a href="#get-api-v1-streaming-health" id="get-api-v1-streaming-health"></a>

Returns `OK` when streaming service is fine. Added in 2.5.0

#### GET /api/v1/streaming/user <a href="#get-api-v1-streaming-user" id="get-api-v1-streaming-user"></a>

Returns events that are relevant to the authorized user, i.e. home timeline and notifications

#### GET /api/v1/streaming/public <a href="#get-api-v1-streaming-public" id="get-api-v1-streaming-public"></a>

Returns all public statuses

#### GET /api/v1/streaming/public/local <a href="#get-api-v1-streaming-public-local" id="get-api-v1-streaming-public-local"></a>

Returns all local statuses

#### GET /api/v1/streaming/hashtag?tag=:hashtag <a href="#get-api-v1-streaming-hashtag-tag-hashtag" id="get-api-v1-streaming-hashtag-tag-hashtag"></a>

Returns all public statuses for a particular hashtag

#### GET /api/v1/streaming/hashtag/local?tag=:hashtag <a href="#get-api-v1-streaming-hashtag-local-tag-hashtag" id="get-api-v1-streaming-hashtag-local-tag-hashtag"></a>

Returns all local statuses for a particular hashtag

#### GET /api/v1/streaming/list?list=:list\_id <a href="#get-api-v1-streaming-list-list-list-id" id="get-api-v1-streaming-list-list-list-id"></a>

Returns statuses for a list

#### GET /api/v1/streaming/direct <a href="#get-api-v1-streaming-direct" id="get-api-v1-streaming-direct"></a>

Returns all direct messages

### Stream contents <a href="#stream-contents" id="stream-contents"></a>

The stream will contain events as well as heartbeat comments. Lines that begin with a colon (`:`) can be ignored by parsers, they are simply there to keep the connection open. Events have this structure:

```
event: name
data: payload
```

## WebSocket <a href="#websocket" id="websocket"></a>

For WebSockets, there is only one URL path (`/api/v1/streaming`). The access token as well as the endpoint you are interested in must be provided with query params, respectively `access_token` and `stream`. Query params `list` and `tag` are likewise supported for relevant endpoints.

Possible `stream` values:

* `user`
* `public`
* `public:local`
* `hashtag`
* `hashtag:local`
* `list`
* `direct`

## Event types <a href="#event-types" id="event-types"></a>

| Event             | Description                       | What’s in the payload                                                         |
| ----------------- | --------------------------------- | ----------------------------------------------------------------------------- |
| `update`          | A new status has appeared         | [Status](https://mastodon.gitbook.io/mastodon/jp/entities/status)             |
| `notification`    | A new notification has appeared   | [Notification](https://mastodon.gitbook.io/mastodon/jp/entities/notification) |
| `delete`          | A status has been deleted         | ID of the deleted status                                                      |
| `filters_changed` | Keyword filters have been changed |                                                                               |

The payload is JSON-encoded.

{% hint style="info" %}
In case of `filters_changed` event, `payload` is not defined.
{% endhint %}