TopicTrace API Documentation

The TopicTrace API provides programmatic access to a topic-tracking dataset that turns large-scale web coverage into time-indexed summaries. Query topics and retrieve summaries across daily, weekly, monthly, quarterly, and yearly views—then pull keyword-to-source URL mappings to trace evidence back to original sources.

Topics catalog with coverage date ranges
Time-indexed summaries (daily → yearly) per topic
Sentiment + source counts for trend scanning
Keyword-to-source URLs to validate and explore evidence

🔑 Need API access? Request your API key to start integrating TopicTrace data.

Request Access ↓

🧪 Already have an API key? Test it out directly in the browser with our interactive playground.

Try API Playground ↓

API Host

https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1

Gateway Path

All requests go through the gateway function below. Specify the target operation using the endpoint query parameter.

/topics?endpoint=...

Authentication

All API requests include two headers:

Authorization: Supabase anon token (public) used to call the edge function
X-Api-Key: your TopicTrace API key (used for access + rate limits)

Your TopicTrace API key controls what you can access and how much you can call the API.

curl \ -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -H "X-Api-Key: YOUR_API_KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=topics"

Quick Start

Call topics to get a topic_hash and coverage dates.
Use content_daily, content_weekly, or content_monthly to pull summaries.
Use the matching *_keyword_source endpoint to retrieve keywords and traceable source URLs.

Request Format

Specify the endpoint using the endpoint query parameter. Additional parameters are passed as query parameters.

⚡ Rate Limits

Rate limits are enforced per API key based on your plan. Response headers include X-RateLimit-Limit and X-RateLimit-Remaining to track your usage.

🗓️ Coverage & Backfills

Current coverage begins in December 2025 and expands over time. Historical backfills (e.g., to 2010 for a topic) are available on request for paid plans.

Core Endpoints

GET topics Core ▼

Returns a list of all available topics with their full hierarchy of subtopics. Use this to discover what topics are available for tracking.

Parameters

None required

Response Fields

hash — TEXT: Unique identifier for the topic
topic — TEXT: Main topic name
subtopic — TEXT: Primary subtopic
subtopic1-9 — TEXT: Additional subtopic levels
min_date — INTEGER: Earliest available date (YYYYMMDD)
max_date — INTEGER: Latest available date (YYYYMMDD)

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=topics"

GET dates Core ▼

Returns date dimension information for a specific month, including week numbers, day names, and ISO week data. Useful for building calendar views.

Parameters

Parameter	Type	Description
p_year required	INTEGER	The year (e.g., 2025)
p_month required	INTEGER	The month (1-12)

Response Fields

date — INTEGER: Date ID (YYYYMMDD format)
year — INTEGER: Calendar year
quarter — INTEGER: Quarter (1-4)
month — INTEGER: Month (1-12)
month_name — TEXT: Full month name
week — INTEGER: Week of month
day — INTEGER: Day of month
day_of_week — INTEGER: Day of week (1-7)
day_name — TEXT: Full day name
is_weekend — INTEGER: 1 if weekend, 0 otherwise
iso_year — INTEGER: ISO year
iso_week — INTEGER: ISO week number
week_start_date — INTEGER: Start date of the week
week_end_date — INTEGER: End date of the week

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=dates&p_year=2025&p_month=1"

GET topic_overview Core ▼

Returns overview content for all topics. Perfect for building topic landing pages.

Parameters

None required

Response Fields

topic_hash — TEXT: Unique topic identifier
content — TEXT: Full overview content

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=topic_overview"

Content Endpoints

GET content_daily Content ▼

Returns daily content summaries for a specific topic and month. Includes sentiment analysis and source count.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_year required	INTEGER	The year
p_month required	INTEGER	The month (1-12)

Response Fields

topic_hash — TEXT: Topic identifier
year — INTEGER: Year
iso_year — INTEGER: ISO year
quarter — INTEGER: Quarter
month — INTEGER: Month
week — INTEGER: Week of month
iso_week — INTEGER: ISO week
date_id — INTEGER: Date ID (YYYYMMDD)
sentiment — TEXT: Sentiment (positive/neutral/negative)
content — TEXT: Full content
source_count — INTEGER: Number of sources

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_daily&p_topic_hash=YOUR_TOPIC_HASH&p_year=2025&p_month=1"

GET content_weekly Content ▼

Returns weekly aggregated content summaries for a topic throughout a year. Summaries consolidate daily updates into weekly overviews.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_year required	INTEGER	The year

Response Fields

topic_hash — TEXT: Topic identifier
year — INTEGER: Year
iso_year — INTEGER: ISO year
quarter — INTEGER: Quarter
month — INTEGER: Month
iso_week — INTEGER: ISO week number
start_date — INTEGER: Week start date
end_date — INTEGER: Week end date
sentiment — TEXT: Overall sentiment
content — TEXT: Full weekly summary
source_count — INTEGER: Total sources

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_weekly&p_topic_hash=YOUR_TOPIC_HASH&p_year=2025"

GET content_monthly Content ▼

Returns monthly aggregated content for a topic in a given year. Provides high-level monthly summaries with sentiment and sources.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_year required	INTEGER	The year

Response Fields

topic_hash — TEXT: Topic identifier
year — INTEGER: Year
quarter — INTEGER: Quarter
month — INTEGER: Month
start_date — INTEGER: Month start date
end_date — INTEGER: Month end date
sentiment — TEXT: Monthly sentiment
content — TEXT: Full monthly summary
source_count — INTEGER: Total sources

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_monthly&p_topic_hash=YOUR_TOPIC_HASH&p_year=2025"

GET content_quarterly Content ▼

Returns quarterly content summaries for a topic in a specific year. Ideal for Q1-Q4 reporting and trend analysis.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_year required	INTEGER	The year

Response Fields

topic_hash — TEXT: Topic identifier
year — INTEGER: Year
quarter — INTEGER: Quarter (1-4)
start_date — INTEGER: Quarter start
end_date — INTEGER: Quarter end
sentiment — TEXT: Quarterly sentiment
content — TEXT: Full quarterly summary
source_count — INTEGER: Total sources

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_quarterly&p_topic_hash=YOUR_TOPIC_HASH&p_year=2025"

GET content_yearly Content ▼

Returns yearly content summaries for a topic across all available years. Best for long-term trend analysis and year-over-year comparisons.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier

Response Fields

topic_hash — TEXT: Topic identifier
year — INTEGER: Year
start_date — INTEGER: Year start date
end_date — INTEGER: Year end date
sentiment — TEXT: Yearly sentiment
content — TEXT: Full yearly summary
source_count — INTEGER: Total sources

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_yearly&p_topic_hash=YOUR_TOPIC_HASH"

Source & Keyword Endpoints

GET content_daily_keyword_source Sources ▼

Returns detailed keyword and source information for a specific daily content entry. Includes relevance scores and primary source indicators.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_date_id required	INTEGER	Date ID (YYYYMMDD format)

Response Fields

topic_hash — TEXT: Topic identifier
date_id — INTEGER: Date ID
keyword — TEXT: Associated keyword
source_url — TEXT: Source URL
source_name — TEXT: Source display name
relevance_score — REAL: Relevance score (0-1)
confidence_score — REAL: Confidence score (0-1)
is_primary — BOOLEAN: Primary source flag

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_daily_keyword_source&p_topic_hash=YOUR_TOPIC_HASH&p_date_id=20250115"

GET content_weekly_keyword_source Sources ▼

Returns keyword and source data for a specific ISO week's content.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_iso_year required	INTEGER	ISO year
p_iso_week required	INTEGER	ISO week number (1-53)

Response Fields

topic_hash — TEXT: Topic identifier
iso_year — INTEGER: ISO year
iso_week — INTEGER: ISO week
keyword — TEXT: Associated keyword
source_url — TEXT: Source URL
source_name — TEXT: Source name
relevance_score — REAL: Relevance (0-1)
confidence_score — REAL: Confidence (0-1)
is_primary — BOOLEAN: Primary source

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_weekly_keyword_source&p_topic_hash=YOUR_TOPIC_HASH&p_iso_year=2025&p_iso_week=3"

GET content_monthly_keyword_source Sources ▼

Returns keyword and source data for a specific month's content.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_year required	INTEGER	The year
p_month required	INTEGER	The month (1-12)

Response Fields

topic_hash — TEXT: Topic identifier
year — INTEGER: Year
month — INTEGER: Month
keyword — TEXT: Associated keyword
source_url — TEXT: Source URL
source_name — TEXT: Source name
relevance_score — REAL: Relevance (0-1)
confidence_score — REAL: Confidence (0-1)
is_primary — BOOLEAN: Primary source

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_monthly_keyword_source&p_topic_hash=YOUR_TOPIC_HASH&p_year=2025&p_month=1"

GET content_quarterly_keyword_source Sources ▼

Returns keyword and source data for a specific quarter's content.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_year required	INTEGER	The year
p_quarter required	INTEGER	The quarter (1-4)

Response Fields

topic_hash — TEXT: Topic identifier
year — INTEGER: Year
quarter — INTEGER: Quarter
keyword — TEXT: Associated keyword
source_url — TEXT: Source URL
source_name — TEXT: Source name
relevance_score — REAL: Relevance (0-1)
confidence_score — REAL: Confidence (0-1)
is_primary — BOOLEAN: Primary source

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_quarterly_keyword_source&p_topic_hash=YOUR_TOPIC_HASH&p_year=2025&p_quarter=1"

GET content_yearly_keyword_source Sources ▼

Returns keyword and source data for a specific year's content.

Parameters

Parameter	Type	Description
p_topic_hash required	TEXT	Topic hash identifier
p_year required	INTEGER	The year

Response Fields

topic_hash — TEXT: Topic identifier
year — INTEGER: Year
keyword — TEXT: Associated keyword
source_url — TEXT: Source URL
source_name — TEXT: Source name
relevance_score — REAL: Relevance (0-1)
confidence_score — REAL: Confidence (0-1)
is_primary — BOOLEAN: Primary source

Example Request

curl -H "Authorization: Bearer TOKEN" -H "X-Api-Key: KEY" \ "https://tohblpcjhzaxivhxkecm.supabase.co/functions/v1/topics?endpoint=content_yearly_keyword_source&p_topic_hash=YOUR_TOPIC_HASH&p_year=2025"

Error Codes

Code	Description
400	Bad Request — Missing or invalid endpoint parameter
401	Unauthorized — Missing or invalid API key
403	Forbidden — API key revoked or endpoint not allowed for your plan
413	Payload Too Large — Response exceeds max_rows_per_call limit
429	Too Many Requests — Monthly request limit exceeded
500	Internal Server Error — RPC or system failure

FAQ

Is this a news API?

TopicTrace is a topic-tracking dataset and API. It aggregates coverage into time-indexed summaries and provides source URLs for traceability.

How is this different from asking an LLM?

One-off LLM answers typically rely on a small set of retrieved pages. TopicTrace summaries are built from large-scale coverage collected over time and organized into daily→yearly views with evidence links.

Do you provide raw articles?

TopicTrace provides summaries, keywords, and source URLs so you can validate and explore original coverage.

Request API Access

🎁 Free Plan: 200 rows per request · 200 calls/month · rate limits enforced per API key

Get Your API Key

Interested in integrating TopicTrace data into your application? Fill out the form below to request API access.

Your email client will open with a pre-filled message. Please send the email to complete your request.

Having trouble with the form? You can also send your request directly to topictrace@gmail.com with the following information:

Your Name
Your Email address
A Message describing your use case and requirements

API Playground

🧪 Test the API

Already have an API key? Test the endpoints directly from this page and see the response.

API Key *

Endpoint *