timelines

Read and view timelines of statuses.

Public timeline

GET https://mastodon.example/api/v1/timelines/public

Returns: Array of Status OAuth: Public. Requires app token + read:statuses if the instance has disabled public preview. Version history: 0.0.0 - added 2.3.0 - added only_media 2.6.0 - add min_id 3.0.0 - auth is required if public preview is disabled

Query Parameters

Name	Type	Description
local	boolean	Show only local statuses? Defaults to false.
only_media	boolean	Show only statuses with media attached? Defaults to false.
max_id	string	Return results older than this id
since_id	string	Return results newer than this id
min_id	string	Return results immediately newer than this id
limit	integer	Maximum number of results to return. Defaults to 20.

200 Sample API call with limit=2

[
  {
    "id": "103206804533200177",
    "created_at": "2019-11-26T23:27:31.000Z",
    ...
    "visibility": "public",
    ...
  },
  {
    "id": "103206804086086361",
    "created_at": "2019-11-26T23:27:32.000Z",
    ...
    "visibility": "public",
    ...
  }
]

Hashtag timeline

GET https://mastodon.example/api/v1/timelines/tag/:hashtag

View public statuses containing the given hashtag. Returns: Array of Status OAuth: Public. Requires app token + read:statuses if the instance has disabled public preview. Version history: 0.0.0 - added 2.3.0 - added only_media 2.6.0 - add min_id 3.0.0 - auth is required if public preview is disabled

Path Parameters

Name	Type	Description
:hashtag	string	Content of a #hashtag, not including # symbol.

Query Parameters

Name	Type	Description
local	boolean	If true, return only local statuses. Defaults to false.
only_media	boolean	If true, return only statuses with media attachments. Defaults to false.
max_id	string	Return results older than this ID.
since_id	string	Return results newer than this ID.
min_id	string	Return results immediately newer than this ID.
limit	integer	Maximum number of results to return. Defaults to 20.

200 Sample timeline for the hashtag #cats and limit=2

[
  {
    "id": "103206185588894565",
    "created_at": "2019-11-26T20:50:15.866Z",
    ...
    "visibility": "public",
    ...
    "content": "<p><a href=\"https://mastodon.social/tags/cats\" class=\"mention hashtag\" rel=\"tag\">#<span>cats</span></a></p>",
    ...
    "tags": [
      {
        "name": "cats",
        "url": "https://mastodon.social/tags/cats"
      }
    ],
    ...
  },
  {
    "id": "103203659567597966",
    "created_at": "2019-11-26T10:07:49.000Z",
    ...
    "visibility": "public",
    ...
    "content": "<p>Caught on the hop. 😺 </p><p><a href=\"https://chaos.social/tags/Qualit%C3%A4tskatzen\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>Qualitätskatzen</span></a> <a href=\"https://chaos.social/tags/cats\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>cats</span></a> <a href=\"https://chaos.social/tags/mastocats\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>mastocats</span></a> <a href=\"https://chaos.social/tags/catsofmastodon\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>catsofmastodon</span></a> <a href=\"https://chaos.social/tags/Greece\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>Greece</span></a> <a href=\"https://chaos.social/tags/Agistri\" class=\"mention hashtag\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">#<span>Agistri</span></a><br>(photo: <span class=\"h-card\"><a href=\"https://chaos.social/@kernpanik\" class=\"u-url mention\" rel=\"nofollow noopener noreferrer\" target=\"_blank\">@<span>kernpanik</span></a></span> | license: CC BY-NC-SA 4.0)</p>",
    ...
    "tags": [
      {
        "name": "qualitätskatzen",
        "url": "https://mastodon.social/tags/qualit%C3%A4tskatzen"
      },
      {
        "name": "cats",
        "url": "https://mastodon.social/tags/cats"
      },
      {
        "name": "mastocats",
        "url": "https://mastodon.social/tags/mastocats"
      },
      {
        "name": "catsofmastodon",
        "url": "https://mastodon.social/tags/catsofmastodon"
      },
      {
        "name": "greece",
        "url": "https://mastodon.social/tags/greece"
      },
      {
        "name": "agistri",
        "url": "https://mastodon.social/tags/agistri"
      }
    ],
    ...
  }
]

Home timeline

GET https://mastodon.example/api/v1/timelines/home

View statuses from followed users. Returns: Array of Status OAuth: User + read:statuses Version history: 0.0.0 - added 2.6.0 - add min_id

Query Parameters

Name	Type	Description
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	string	Maximum number of results to return. Defaults to 20.
local	boolean	Return only local statuses?

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Statuses in your home timeline will be returned

[
  {
    "id": "103206791453397862",
    "created_at": "2019-11-26T23:24:13.113Z",
    ...
  },
  ...
]

206 Home feed is regenerating

401

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

List timeline

GET https://mastodon.example/api/v1/timelines/list/:list_id

View statuses in the given list timeline. Returns: Array of Status OAuth: User token + read:lists Version history: 2.1.0 - added 2.6.0 - add min_id

Path Parameters

Name	Type	Description
:list_id	string	Local ID of the list in the database.

Query Parameters

Name	Type	Description
max_id	string	Return results older than this ID.
since_id	string	Return results newer than this ID.
min_id	string	Return results immediately newer than this ID.
limit	integer	Maximum number of results to return. Defaults to 20.Return results older than this ID.

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Statuses in this list will be returned.

[
  {
    "id": "103206791453397862",
    "created_at": "2019-11-26T23:24:13.113Z",
    ...
  },
  ...
]

401

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

[DEPRECATED] Direct timeline

GET /api/v1/timelines/direct

View statuses with a "direct" privacy, from your account or in your notifications. Returns: Array of Status OAuth: User token + read:statuses Version history: x.x.x - added 2.6.0 - add min_id. deprecated in favor of conversations 3.0.0 - removed

Query Parameters

Name	Type	Description
limit	string	Maximum number of results to return. Defaults to 20.
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

Headers

Name	Type	Description
Authorization	string	Bearer <user token>

200 Statuses with direct visibility, authored by you or mentioning you. Statuses are not grouped by conversation, but are simply returned in chronological order.

[
  {
    "id": "103206185588894565",
    "created_at": "2019-11-26T20:50:15.866Z",
    ...
    "visibility": "direct",
    ...
  },
  ...
]

401

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