timelines

Read and view timelines of statuses.

get
Public timeline

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
3.1.4 - added remote
3.3.0 - both min_id and max_id can be used at the same time now

Request

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

Response

200: Success

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",
    ...
  }
]

get
Hashtag timeline

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
3.3.0 - both min_id and max_id can be used at the same time now

Request

Path Parameters
:hashtag
required
string
Content of a #hashtag, not including # symbol.
Query Parameters
local
optional
boolean
If true, return only local statuses. Defaults to false.
only_media
optional
boolean
If true, return only statuses with media attachments. Defaults to false.
max_id
optional
string
Return results older than this ID.
since_id
optional
string
Return results newer than this ID.
min_id
optional
string
Return results immediately newer than this ID.
limit
optional
integer
Maximum number of results to return. Defaults to 20.

Response

200: Success

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"
      }
    ],
    ...
  }
]

get
Home timeline

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
3.3.0 - both min_id and max_id can be used at the same time now

Request

Headers
Authorization
required
string
Bearer <user token>
Query Parameters
max_id
optional
string
Return results older than id
since_id
optional
string
Return results newer than id
min_id
optional
string
Return results immediately newer than id
limit
optional
string
Maximum number of results to return. Defaults to 20.
local
optional
boolean
Return only local statuses?

Response

200: Success

Statuses in your home timeline will be returned

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

206:

Home feed is regenerating

401: Unauthorized

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

get
List timeline

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
3.3.0 - both min_id and max_id can be used at the same time now

Request

Path Parameters
:list_id
required
string
Local ID of the list in the database.
Headers
Authorization
required
string
Bearer <user token>
Query Parameters
max_id
optional
string
Return results older than this ID.
since_id
optional
string
Return results newer than this ID.
min_id
optional
string
Return results immediately newer than this ID.
limit
optional
integer
Maximum number of results to return. Defaults to 20.Return results older than this ID.

Response

200: Success

Statuses in this list will be returned.

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

401: Unauthorized

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

get
\[DEPRECATED\] Direct timeline

/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

Request

Headers
Authorization
required
string
Bearer <user token>
Query Parameters
limit
optional
string
Maximum number of results to return. Defaults to 20.
max_id
optional
string
Return results older than ID
since_id
optional
string
Return results newer than ID
min_id
optional
string
Return results immediately newer than ID

Response

200: Success

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: Unauthorized

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

Last updated December 27, 2020 · Improve this page