or run

npx @tessl/cli init

Timeline Retrieval

Complete timeline access including home, public, hashtag, list, and direct timelines.

Timeline Types

Mastodon provides several timeline types:

Home Timeline - Statuses from followed accounts and own statuses
Public Timeline - All public statuses (local or federated)
Hashtag Timeline - Statuses containing specific hashtags
List Timeline - Statuses from accounts in a specific list
Direct Timeline - Direct messages
Media Timeline - Public statuses with media (experimental)
Trending Statuses - Popular/trending content

Timeline Methods

GetTimelineHome { .api }

func (c *Client) GetTimelineHome(ctx context.Context, pg *Pagination) ([]*Status, error)

Returns the home timeline (followed accounts and own statuses).

Parameters:

ctx - Context for cancellation/timeout
pg - Pagination parameters (optional, nil for defaults)

Returns: Slice of Status objects or error

Example:

statuses, err := client.GetTimelineHome(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, status := range statuses {
    fmt.Printf("@%s: %s\n", status.Account.Acct, status.Content)
}

Example with Pagination:

pg := &mastodon.Pagination{
    Limit: 20,
}
statuses, err := client.GetTimelineHome(ctx, pg)
if err != nil {
    log.Fatal(err)
}

// Get next page
if len(statuses) > 0 {
    pg.MaxID = statuses[len(statuses)-1].ID
    moreStatuses, err := client.GetTimelineHome(ctx, pg)
    // ...
}

GetTimelinePublic { .api }

func (c *Client) GetTimelinePublic(ctx context.Context, isLocal bool, pg *Pagination) ([]*Status, error)

Returns the public timeline.

Parameters:

ctx - Context for cancellation/timeout
isLocal - If true, only show local statuses; if false, show federated timeline
pg - Pagination parameters (optional)

Returns: Slice of Status objects or error

Example:

// Local timeline
localStatuses, err := client.GetTimelinePublic(ctx, true, nil)
if err != nil {
    log.Fatal(err)
}

// Federated timeline
federatedStatuses, err := client.GetTimelinePublic(ctx, false, nil)
if err != nil {
    log.Fatal(err)
}

GetTimelineHashtag { .api }

func (c *Client) GetTimelineHashtag(ctx context.Context, tag string, isLocal bool, pg *Pagination) ([]*Status, error)

Returns the hashtag timeline for a specific tag.

Parameters:

ctx - Context for cancellation/timeout
tag - Hashtag name (without '#' prefix)
isLocal - If true, only show local statuses
pg - Pagination parameters (optional)

Returns: Slice of Status objects or error

Example:

statuses, err := client.GetTimelineHashtag(ctx, "golang", false, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Found %d statuses with #golang\n", len(statuses))

GetTimelineHashtagMultiple { .api }

func (c *Client) GetTimelineHashtagMultiple(ctx context.Context, tag string, isLocal bool, td *TagData, pg *Pagination) ([]*Status, error)

Returns the hashtag timeline with additional tag filters (any/all/none).

Parameters:

ctx - Context for cancellation/timeout
tag - Primary hashtag name (without '#' prefix)
isLocal - If true, only show local statuses
td - Tag filter data (any/all/none conditions)
pg - Pagination parameters (optional)

Returns: Slice of Status objects or error

Example:

// Posts with #golang AND (#programming OR #coding) but NOT #tutorial
tagData := &mastodon.TagData{
    All:  []string{"programming"},
    Any:  []string{"coding", "development"},
    None: []string{"tutorial"},
}

statuses, err := client.GetTimelineHashtagMultiple(ctx, "golang", false, tagData, nil)
if err != nil {
    log.Fatal(err)
}

GetTimelineList { .api }

func (c *Client) GetTimelineList(ctx context.Context, id ID, pg *Pagination) ([]*Status, error)

Returns the timeline for a specific list.

Parameters:

ctx - Context for cancellation/timeout
id - List ID
pg - Pagination parameters (optional)

Returns: Slice of Status objects or error

Example:

listID := "123456"
statuses, err := client.GetTimelineList(ctx, listID, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("List has %d recent statuses\n", len(statuses))

GetTimelineDirect { .api }

func (c *Client) GetTimelineDirect(ctx context.Context, pg *Pagination) ([]*Status, error)

Returns direct message timeline.

Parameters:

ctx - Context for cancellation/timeout
pg - Pagination parameters (optional)

Returns: Slice of Status objects with direct visibility or error

Example:

directMessages, err := client.GetTimelineDirect(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, dm := range directMessages {
    fmt.Printf("DM from @%s: %s\n", dm.Account.Acct, dm.Content)
}

GetTimelineMedia { .api }

func (c *Client) GetTimelineMedia(ctx context.Context, isLocal bool, pg *Pagination) ([]*Status, error)

Returns the media timeline (statuses with media attachments).

Parameters:

ctx - Context for cancellation/timeout
isLocal - If true, only show local statuses
pg - Pagination parameters (optional)

Returns: Slice of Status objects with media or error

Note: This is an experimental feature of pawoo.net and may not be available on all Mastodon instances.

GetTrendingStatuses { .api }

func (c *Client) GetTrendingStatuses(ctx context.Context, pg *Pagination) ([]*Status, error)

Returns trending/explore statuses.

Parameters:

ctx - Context for cancellation/timeout
pg - Pagination parameters (optional)

Returns: Slice of trending Status objects or error

Example:

trending, err := client.GetTrendingStatuses(ctx, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Found %d trending statuses\n", len(trending))

Pagination

All timeline methods support pagination using the Pagination struct:

type Pagination struct {
    MaxID   ID    // Get statuses older than this ID
    SinceID ID    // Get statuses newer than this ID
    MinID   ID    // Get statuses immediately newer than this ID
    Limit   int64 // Maximum number of statuses to return
}

Example: Scrolling Through Timeline

// Initial fetch
pg := &mastodon.Pagination{Limit: 40}
statuses, err := client.GetTimelineHome(ctx, pg)
if err != nil {
    log.Fatal(err)
}

// Process statuses...
for _, status := range statuses {
    fmt.Printf("@%s: %s\n", status.Account.Acct, status.Content)
}

// Load older statuses (scroll down)
if len(statuses) > 0 {
    pg.MaxID = statuses[len(statuses)-1].ID
    olderStatuses, err := client.GetTimelineHome(ctx, pg)
    // ...
}

Example: Real-time Updates

// Get latest statuses
latestStatuses, err := client.GetTimelineHome(ctx, nil)
if err != nil {
    log.Fatal(err)
}

// Later, check for new statuses
if len(latestStatuses) > 0 {
    pg := &mastodon.Pagination{
        SinceID: latestStatuses[0].ID,
    }
    newStatuses, err := client.GetTimelineHome(ctx, pg)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Found %d new statuses\n", len(newStatuses))
}

Tag Filter Data

The TagData struct is used for advanced hashtag filtering:

type TagData struct {
    Any  []string // Statuses containing ANY of these tags
    All  []string // Statuses containing ALL of these tags
    None []string // Statuses containing NONE of these tags
}

Example: Complex Tag Filtering

// Find posts about #opensource that mention #golang or #rust
// but exclude #beginners
tagData := &mastodon.TagData{
    All:  []string{"opensource"},
    Any:  []string{"golang", "rust"},
    None: []string{"beginners"},
}

statuses, err := client.GetTimelineHashtagMultiple(
    ctx,
    "programming",  // Primary tag
    false,          // Include federated
    tagData,
    nil,
)

Best Practices

1. Pagination Limits

Set reasonable limits to avoid overwhelming the server:

pg := &mastodon.Pagination{
    Limit: 40, // Typical web UI limit
}

2. Error Handling

Always handle errors, especially for rate limiting:

statuses, err := client.GetTimelineHome(ctx, pg)
if err != nil {
    if apiErr, ok := err.(*mastodon.APIError); ok {
        if apiErr.StatusCode == 429 {
            // Rate limited, wait before retrying
            time.Sleep(time.Minute)
        }
    }
    log.Fatal(err)
}

3. Context Timeouts

Use context timeouts for network operations:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

statuses, err := client.GetTimelineHome(ctx, nil)

4. Caching

Consider caching timeline results to reduce API calls:

type TimelineCache struct {
    statuses  []*mastodon.Status
    fetchedAt time.Time
    ttl       time.Duration
}

func (tc *TimelineCache) Get(client *mastodon.Client, ctx context.Context) ([]*mastodon.Status, error) {
    if time.Since(tc.fetchedAt) < tc.ttl {
        return tc.statuses, nil
    }

    statuses, err := client.GetTimelineHome(ctx, nil)
    if err != nil {
        return nil, err
    }

    tc.statuses = statuses
    tc.fetchedAt = time.Now()
    return statuses, nil
}

Timeline Streaming

For real-time timeline updates, consider using the streaming API:

// HTTP Streaming
events, err := client.StreamingUser(ctx)
if err != nil {
    log.Fatal(err)
}

for event := range events {
    switch e := event.(type) {
    case *mastodon.UpdateEvent:
        fmt.Printf("New status: %s\n", e.Status.Content)
    case *mastodon.DeleteEvent:
        fmt.Printf("Deleted status: %s\n", e.ID)
    case *mastodon.ErrorEvent:
        log.Printf("Stream error: %v\n", e.Err)
    }
}

See Streaming for complete streaming documentation.

Version

Tile

Files

timelines.mddocs/

Timeline Retrieval

Timeline Types

Timeline Methods

GetTimelineHome { .api }

GetTimelinePublic { .api }

GetTimelineHashtag { .api }

GetTimelineHashtagMultiple { .api }

GetTimelineList { .api }

GetTimelineDirect { .api }

GetTimelineMedia { .api }

GetTrendingStatuses { .api }

Pagination

Example: Scrolling Through Timeline

Example: Real-time Updates

Tag Filter Data

Example: Complex Tag Filtering

Best Practices

1. Pagination Limits

2. Error Handling

3. Context Timeouts

4. Caching

Timeline Streaming

Related Types

Version

Tile

Files

timelines.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Timeline Retrieval

Timeline Types

Timeline Methods

GetTimelineHome { .api }

GetTimelinePublic { .api }

GetTimelineHashtag { .api }

GetTimelineHashtagMultiple { .api }

GetTimelineList { .api }

GetTimelineDirect { .api }

GetTimelineMedia { .api }

GetTrendingStatuses { .api }

Pagination

Example: Scrolling Through Timeline

Example: Real-time Updates

Tag Filter Data

Example: Complex Tag Filtering

Best Practices

1. Pagination Limits

2. Error Handling

3. Context Timeouts

4. Caching

Timeline Streaming

Related Types

timelines.mddocs/