Skip to main content
GET
Get Global Topics Timeseries

Overview

Retrieve historical timeseries data for trending topics. This endpoint allows you to analyze how topics evolved over time, track when topics first appeared, and understand historical narrative trends in the crypto ecosystem.

Query Parameters

start (required)

Start of the time range in ISO 8601 format. Example: ?start=2025-01-01T00:00:00Z

end (required)

End of the time range in ISO 8601 format. Example: ?end=2025-01-07T23:59:59Z

granularity

Time interval for data points:
  • 1d (default): Daily data points
  • 1h: Hourly data points
Example: ?granularity=1d

assetIDs

Filter topics by associated assets. Provide a comma-separated list of asset identifiers. Accepts any combination of UUIDs, slugs, or symbols. Examples:
  • By slug: ?assetIDs=bitcoin,ethereum,solana
  • By symbol: ?assetIDs=BTC,ETH,SOL
  • By UUID: ?assetIDs=21c795f5-1bfd-40c3-858e-e9d7e820c6d0
  • Mixed: ?assetIDs=bitcoin,ETH,21c795f5-1bfd-40c3-858e-e9d7e820c6d0

Time Range Limits

  • Maximum range: 90 days
  • Default range: 7 days (if not specified)
  • Ranges are automatically truncated to granularity boundaries for better caching

Response Structure

Each data point in the timeseries includes:
  • time: Unix timestamp of the data point
  • title: Topic title
  • summary: Topic summary
  • content: Detailed content with bullet points
  • classes: Array of classification tags
  • rank: Ranking of the topic at this timestamp (1 = most trending)
  • topDocuments: Links to source documents
    • url: Document URL
    • type: Document type (x_post, article, etc.)
  • documentCount: Number of source documents
  • assets: Array of related crypto assets
    • id: Asset UUID
    • name: Asset name
    • symbol: Asset symbol
    • slug: Asset slug

Usage Examples

Get Daily Topics for a Week

Get Hourly Topics for 24 Hours

Get Daily Topics for Specific Assets

Filter by Asset Symbol

Analysis Use Cases

Track Topic Persistence

Identify which topics stay relevant over extended periods vs. flash-in-the-pan news.

Analyze Topic Classes Over Time

See how different types of topics (security, partnerships, etc.) trend seasonally.

Monitor Asset Narratives

Track how often specific assets appear in trending topics over time. Use the assetIDs filter to focus on assets in your portfolio.

Detect Narrative Shifts

Identify when new topics emerge or old topics fade from attention.

Compare Time Periods

Analyze how topic landscape differs between bull and bear markets.

Best Practices

  1. Use Appropriate Granularity: Daily for long-term trends, hourly for real-time analysis
  2. Respect Time Limits: Don’t request more than 90 days at once
  3. Handle Empty Results: Some time periods may have no trending topics
  4. Cache Historical Data: Past data doesn’t change, cache it locally
  5. Batch Requests: For large date ranges, break into multiple smaller requests

Response Format

Topics are sorted by:
  1. Timestamp (ascending)
  2. Trending score (descending - higher ranks first)
This means for each timestamp, you’ll see the most important topics first.

Error Handling

Common errors:
  • 400 Bad Request: Invalid date format or time range exceeds 90 days
  • 403 Forbidden: Insufficient API permissions
  • 500 Internal Server Error: Temporary service issue, retry with backoff

Authorizations

x-messari-api-key
string
header
required

API key for authentication. Get your key at https://messari.io/account/api

Query Parameters

start
string<date-time>
default:2025-10-01T00:00:00Z
required

Start of time range in ISO 8601 format

Example:

"2025-10-01T00:00:00Z"

end
string<date-time>
default:2025-10-03T23:59:59Z
required

End of time range in ISO 8601 format

Example:

"2025-10-03T23:59:59Z"

granularity
enum<string>
default:1d

Time granularity for data points

Available options:
1d,
1h
assetIDs
string

Comma-separated list of asset identifiers to filter topics by associated assets. Accepts UUIDs, slugs, or symbols.

Example:

"bitcoin,ETH,21c795f5-1bfd-40c3-858e-e9d7e820c6d0"

Response

Successfully retrieved topics timeseries

error
string | null
data
object[]