# 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](/mastodon/entities/status.md)             |
| `notification`    | A new notification has appeared   | [Notification](/mastodon/entities/notification.md) |
| `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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mastodon.gitbook.io/mastodon/methods/timelines/streaming.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.