Public REST API for querying political speech, transcript segments, speakers, topics, usage, API keys, and saved analyses.
Base URL: https://api.meshapi.app
Interactive reference: /docs in non-production environments (disabled on the production API)
Use this as the source for public API documentation on the Mesh frontend.
curl "https://api.meshapi.app/v1/events?limit=10&has_transcript=true" \
-H "X-API-Key: mesh_your_key_here"
All /v1/* endpoints require authentication. GET /health is public.
Pass your API key in the X-API-Key header:
X-API-Key: mesh_your_key_here
Create and manage API keys from your account dashboard on the Mesh web app.
For AI clients, the Mesh MCP server exposes every public API operation as a tool. The local source package uses an API key for data tools and a user JWT for key management. The hosted Python Streamable HTTP endpoint uses browser login at https://api.meshapi.app/mcp.
| Pool | What counts | Reset |
|---|---|---|
| Transcript pulls | GET /v1/events/{event_id}/segments or a batch entry returning at least 50 segments for one event; deduped by event per UTC day | Daily and monthly on paid plans |
| Searches | GET /v1/segments/search, GET /v1/search/events, GET /v1/topics/{slug}/segments | Daily for API keys and hosted MCP |
| Other endpoints | Metadata, usage, topic listings, speakers, saved analyses | Unmetered |
| Plan | Daily transcript pulls | Daily searches | Monthly transcript cap |
|---|---|---|---|
| Free | 3 full-event unlocks/day shared by web, API, and MCP | 10/day for API/MCP | Full access limited by daily unlocks |
| Trial (14 days) | 5/day | 50/day | 150/month |
| Pro | 15/day | 150/day | 450/month |
| Max | 30/day | 300/day | 900/month |
| Enterprise | Contract-defined | Contract-defined | Contract-defined |
Caps are account-wide. API keys and hosted MCP share the daily search budget. Free full-event unlocks are shared by browser, API keys, and MCP and reset at 00:00 UTC; refetching the same unlocked event that day costs no additional unlock. Paid daily transcript usage counts each qualifying event once per UTC day; monthly usage counts each qualifying event once per billing period. Paid monthly caps reset on the first of each month.
Searches, word-count analyses, metadata, and transcript context requests returning 1–49 segments do not spend transcript pulls. For paid API-key and MCP calls, a pull is charged only when one event returns 50 or more segments in one response. Separate pages returning fewer than 50 segments each do not count as pulls. Free-plan access still requires a daily unlock to see beyond the first 15 segments of a locked event.
For "how many times was this word said?", use run_analysis with analysis_type: "word_frequency" and count_mode: "occurrences". Its default segments mode counts segments containing the term instead. Occurrences are case-insensitive text matches, including matches inside longer words. The analysis does not consume the search or transcript-pull quota; Free-plan results still cover only visible preview segments and events unlocked that day. Segment search finds matching text and consumes one daily API/MCP search, but no transcript pull.
In addition to quota caps, all API-key requests are subject to a per-key request-per-minute rate limit:
| Plan | Requests per minute |
|---|---|
| Free / Trial / Pro / Max | 60 |
| Enterprise | 300 |
JWT (web and hosted MCP) callers have a separate 120 req/min limit per user. Rate-limited requests return 429 with a Retry-After header.
List endpoints use a paginated envelope:
{
"data": [],
"next_cursor": "dGVzdA==",
"count": 50
}
Single-resource endpoints return the object directly. Errors return:
{ "detail": "Message describing the error" }
| Status | Meaning |
|---|---|
| 400 | Invalid parameter or request body |
| 401 | Missing, invalid, or expired credentials |
| 403 | Account disabled, resource outside key scope, or plan-restricted operation |
| 404 | Resource not found |
| 409 | Conflict, such as max active keys reached |
| 422 | Validation error |
| 429 | Daily/monthly quota exceeded |
Quota errors include useful reset headers when applicable:
Retry-AfterX-Pull-Budget-ResetSpeaker identity has two layers:
Fox World Cup Announcers. Use primary_speaker_id on event endpoints.segment_speaker_id on segment endpoints and segment search.The legacy speaker_id parameter remains supported for compatibility, but its meaning depends on the endpoint: on GET /v1/events it aliases primary_speaker_id; on segment endpoints it aliases segment_speaker_id.
GET /health
Public health check.
{ "status": "ok" }
GET /v1/events
List events. Use has_transcript=true to browse events with transcript data.
Common query params:
| Param | Type | Description |
|---|---|---|
q | string | Optional full-text search on event title |
event_type | string | Event type such as remarks, press_conference, rally, interview |
primary_speaker_id | UUID | Filter by event attribution / primary speaker |
primary_speaker_ids | string | Comma-separated UUIDs (max 20). Returns events where ANY listed speaker is primary. |
segment_speaker_id | UUID | Filter to events where this resolved speaker appears in transcript segments |
segment_speaker_ids | string | Comma-separated resolved segment speaker UUIDs |
speaker_id | UUID | Legacy alias for primary_speaker_id |
speaker_ids | string | Legacy alias for primary_speaker_ids |
topic_slug | string | Filter by topic |
city | string | Partial city match |
state_code | string | Exact state code |
start_date | date | Events on or after this date |
end_date | date | Events on or before this date |
updated_after | datetime | Incremental sync watermark. Returns only events with updated_at > updated_after. |
sort | string | event_date_desc (default), event_date_asc, speaker_asc, event_title_asc, relevance |
include | string | Comma-separated optional expansions. Use event_speakers for curated participant assignments and/or segment_speakers for resolved transcript speaker summaries. |
limit | int | Page size, default 50 |
cursor | string | Cursor from previous response |
Event rows include updated_at (RFC 3339 timestamp). Use this field to checkpoint incremental syncs.
With include=event_speakers, each event also includes its curated participants as objects containing speaker_id, canonical_name, and speaker_role. Participant assignments are loaded once per result page.
When updated_after is omitted, pagination uses sort-aware opaque keyset cursors. A cursor is valid only with the same filters and sort value; changing either returns 422.
When updated_after is provided, the endpoint switches to stable keyset pagination ordered by (updated_at, event_id) ascending. Reuse the same updated_after value for every page in that sync run.
sort is not supported with updated_after sync mode.
GET /v1/events/{event_id}
Get one event. The response includes primary_speaker, event_speakers, segment_speakers, and speaker_summary by default so clients can distinguish event attribution, curated participant roles, and who actually spoke. Each event_speakers item contains speaker_id, canonical_name, and speaker_role.
GET /v1/events/{event_id}/segments
Get transcript segments for one event.
Common query params:
| Param | Type | Description |
|---|---|---|
limit | int | Page size, default 49; 1–49 returned segments do not spend a paid-plan pull |
cursor | string | Cursor from previous response |
segment_speaker_id | UUID | Filter to one resolved segment speaker |
speaker_id | UUID | Legacy alias for segment_speaker_id |
topic_slug | string | Filter to one topic |
unlock | boolean | Free-plan users can set unlock=true to spend one daily unlock |
On the Free plan, API keys and MCP work like the browser: a locked event returns only segments with idx < 15 and a preview_notice explaining the limit. The response also includes unlock_required, preview_truncated, total_segments, and daily_unlocks_remaining. Previews cost no unlock and cannot be paginated. Pass unlock=true to spend one of the account's three daily unlocks and read the full event. The same event stays unlocked until 00:00 UTC. Paid plans receive full access without this preview limit.
For paid API-key and MCP callers, a response with fewer than 50 segments provides context without spending a transcript pull. A response with 50 or more segments spends one pull for that event, subject to daily and monthly caps.
POST /v1/events/batch-segments
Pull transcripts for multiple events in a single request. Designed for bulk data collection workflows. Requires an API key or hosted MCP authorization; unavailable to ordinary browser JWT callers.
Request body:
{
"event_ids": ["uuid1", "uuid2", "uuid3"],
"limit_per_event": 500
}
| Field | Type | Description |
|---|---|---|
event_ids | UUID[] | Event UUIDs to pull transcripts for. Max 25 (enterprise) or 10 (other plans). |
limit_per_event | int | Max segments per event, 1–500, default 500. |
Response:
{
"results": [
{
"event_id": "uuid1",
"segments": [...],
"next_cursor": null,
"count": 142
}
],
"skipped": [
{ "event_id": "uuid3", "reason": "daily_cap_exceeded" }
],
"pulls_used": 1,
"pulls_remaining_daily": 14,
"pulls_remaining_monthly": 449
}
Each event returning at least 50 segments counts as one daily transcript pull, deduped by event per UTC day and once per monthly billing period. Entries returning fewer than 50 segments consume no pull. Billable events that would exceed the daily or monthly cap are returned in skipped with the reason; smaller context entries can still succeed. If an event needs more than limit_per_event segments, the entry includes a next_cursor that can be passed to GET /v1/events/{event_id}/segments?cursor=...&limit=500 to continue paginating that event.
Not available on the Free plan. Possible skip reasons: daily_cap_exceeded, monthly_cap_exceeded, not_found, speaker_not_in_scope, before_scope_date_range, after_scope_date_range.
GET /v1/events/{event_id}/topics
List topics attached to an event.
GET /v1/events/{event_id}/resolutions
List Kalshi market resolutions linked to an event when available.
GET /v1/event-types
List the valid values accepted by event-type filters, ordered by event_type.
[
{
"event_type": "press_conference",
"display_name": "Press Conference",
"description": "Event where media ask questions of officials."
}
]
GET /v1/segments/search
Search transcript segments across events.
Common query params:
| Param | Type | Description |
|---|---|---|
q | string | Full-text segment search |
segment_speaker_id | UUID | Filter by resolved segment speaker |
primary_speaker_id | UUID | Constrain search to events attributed to this primary speaker |
speaker_expand | string | Set to children to expand segment_speaker_id through speaker relationships |
speaker_id | UUID | Legacy alias for segment_speaker_id |
topic_slug | string | Filter by topic |
event_type | string | Filter by event type |
start_date | date | Event start date lower bound |
end_date | date | Event start date upper bound |
sort | string | relevance (default), event_date_desc, event_date_asc, speaker_asc, event_title_asc |
limit | int | Page size |
cursor | string | Cursor from previous response |
Free-plan transcript search returns only the first 15 segments of each locked event plus all segments of events you unlocked that day. The preview_notice field explains this restriction in search results. Paid plans search the full corpus. API key and hosted MCP searches consume the same daily search allowance.
Segment search cursors are opaque keyset snapshots. A cursor is valid only with the same q + filter + sort values; changing any of those returns 422.
GET /v1/search/events
Unified event-level search for frontend "All" mode. Combines title matches and transcript-segment matches, deduplicates by event_id, applies sort server-side, then paginates with one keyset cursor.
Common query params:
| Param | Type | Description |
|---|---|---|
q | string | Optional search text used for title and transcript matching |
event_id | UUID | Optional single-event scope |
event_type | string | Filter by event type |
primary_speaker_id | UUID | Filter by event primary speaker |
segment_speaker_id | UUID | Filter by resolved segment speaker |
speaker_expand | string | Set to children to expand speaker/group filters |
speaker_id | UUID | Legacy alias for segment_speaker_id |
topic_slug | string | Filter by topic slug |
start_date | date | Event start date lower bound |
end_date | date | Event start date upper bound |
has_transcript | boolean | true returns events with transcript data only; use this for transcript-backed All-mode results |
sort | string | relevance (default), event_date_desc, event_date_asc, speaker_asc, event_title_asc |
limit | int | Page size |
cursor | string | Cursor from previous response |
Speaker filtering uses union semantics: primary_speaker_id selects the event/title branch by event attribution, while segment_speaker_id selects the transcript-match branch by resolved speaker (with speaker_expand=children applied to that resolved-speaker branch). Supplying both does not require an event to satisfy both conditions.
Each result row includes event card fields plus match metadata:
primary_speaker_id and primary_speaker_name identify the event attribution speaker (not per-segment resolved speaker)title_matchmatching_segment_count (visibility-filtered for Free plan)best_snippet, best_snippet_start_time_ms, best_snippet_idx, best_snippet_segment_idtopics: string[] of canonical event-topic slugsspeakers: string[] of canonical event-attribution speaker namesmatched_segment_speakers: string[] of canonical resolved-speaker names on visible transcript matchesnum_questions, starts_at, event_typeEvent-search cursors are opaque keyset snapshots. A cursor is valid only with the same q + filters + sort; reusing it with different parameters returns 422.
Free-plan visibility restrictions are applied before transcript counts/snippets are computed, so restricted transcript rows do not leak through match metadata.
GET /v1/speakers
List speakers.
GET /v1/speakers/{speaker_id}
Get one speaker.
GET /v1/speakers/{speaker_id}/events
List events where the speaker is primary or appears in resolved transcript segments.
GET /v1/speakers/{speaker_id}/children
List direct child speakers for an umbrella/group speaker.
GET /v1/speakers/{speaker_id}/parents
List umbrella/group speakers that include this speaker.
GET /v1/speakers/{speaker_id}/stats
Get speaker-level statistics when available.
GET /v1/topics
List topics. Add hierarchy=true to return parent/child structure.
GET /v1/topics/{slug}
Get one topic.
GET /v1/topics/{slug}/segments
Browse transcript segments attached to one topic.
GET /v1/usage
Return your current plan, daily transcript pulls, daily searches, monthly transcript usage, and trial metadata. Does not consume quota.
Important fields:
| Field | Description |
|---|---|
plan | Current effective plan |
daily_transcript_pulls_used / daily_transcript_pulls_cap | Transcript pull usage today |
daily_searches_used / daily_searches_cap | Search usage today |
monthly_transcript_pulls_used / monthly_transcript_pulls_cap | Monthly transcript ceiling |
trial_started_at / trial_ends_at | Trial metadata, if applicable |
GET /v1/pulls
List events fetched through an API key or hosted MCP with at least 50 segments in one response, and whether Mesh has newer transcript data available. Short context reads do not appear here.
Common query params:
| Param | Type | Description |
|---|---|---|
limit | int | Page size |
offset | int | Offset pagination value |
api_key_id | UUID | Optional key-specific history filter |
Use has_updates to show stale transcript pulls in a user dashboard.
Manage your API keys from the Mesh web app. Keys can be created, listed, and revoked from your account dashboard.
The raw key value is shown once at creation. Store it securely. It cannot be retrieved again.
POST /v1/analyses/run
Run supported analysis jobs over the transcript corpus.
POST /v1/analyses/word-streaks
Run word-streak analysis.
GET /v1/analyses
List saved analyses.
POST /v1/analyses
Save an analysis configuration.
GET /v1/analyses/{analysis_id}
Get one saved analysis.
PUT /v1/analyses/{analysis_id}
Update a saved analysis.
DELETE /v1/analyses/{analysis_id}
Delete a saved analysis.
List all transcribed events
curl "https://api.meshapi.app/v1/events?has_transcript=true&limit=50" \
-H "X-API-Key: mesh_your_key_here"
Results are paginated. Pass the next_cursor value from the response as ?cursor=... to fetch the next page. Repeat until next_cursor is null.
Filter events by primary speaker
curl "https://api.meshapi.app/v1/events?primary_speaker_id=381194fe-4856-4945-9e49-9809be82e924&has_transcript=true" \
-H "X-API-Key: mesh_your_key_here"
Get speaker UUIDs from GET /v1/speakers. speaker_id still works here as a legacy alias, but new clients should use primary_speaker_id.
Filter events by segment speaker
curl "https://api.meshapi.app/v1/events?segment_speaker_id=381194fe-4856-4945-9e49-9809be82e924&has_transcript=true" \
-H "X-API-Key: mesh_your_key_here"
This returns events where that speaker appears in resolved transcript segments, even if the event's primary speaker is an umbrella/group speaker.
Filter events by topic
curl "https://api.meshapi.app/v1/events?topic_slug=nato&has_transcript=true" \
-H "X-API-Key: mesh_your_key_here"
Browse available topic slugs with GET /v1/topics.
Filter events by date range
curl "https://api.meshapi.app/v1/events?start_date=2026-01-01&end_date=2026-03-31&has_transcript=true" \
-H "X-API-Key: mesh_your_key_here"
Dates are ISO format. Both start_date and end_date are optional and can be used independently.
Combine multiple filters
curl "https://api.meshapi.app/v1/events?primary_speaker_id=381194fe-...&event_type=press_conference&start_date=2026-01-01&has_transcript=true" \
-H "X-API-Key: mesh_your_key_here"
All filters use AND logic. This returns only press conferences by that speaker from 2026 onward that have transcripts.
Incrementally sync newly changed events
curl "https://api.meshapi.app/v1/events?updated_after=2026-01-01T00:00:00Z&limit=200" \
-H "X-API-Key: mesh_your_key_here"
Store the highest updated_at you have fully processed as your next watermark.
For paginated incremental sync:
updated_after fixed across pages.next_cursor until it is null.event_id client-side within a run.If updated_after and cursor don’t match (for example, using a cursor from a different watermark), the API returns 422.
Pull a full transcript
curl "https://api.meshapi.app/v1/events/70d5bc85-cd9b-4670-94fb-6d5a7433b1d0/segments?limit=500" \
-H "X-API-Key: mesh_your_key_here"
Use limit=500 (the maximum) to minimize round trips. If next_cursor is not null, pass it as ?cursor=...&limit=500 to get the next page. A call returning at least 50 segments spends one transcript pull, deduped by event per UTC day.
Pull segments by speaker within a transcript
curl "https://api.meshapi.app/v1/events/70d5bc85-.../segments?segment_speaker_id=381194fe-...&limit=500" \
-H "X-API-Key: mesh_your_key_here"
Returns only segments from that resolved speaker within the event. Useful for isolating one person's remarks in a multi-speaker transcript. speaker_id remains a legacy alias on segment endpoints.
Pull segments by topic within a transcript
curl "https://api.meshapi.app/v1/events/70d5bc85-.../segments?topic_slug=nato&limit=500" \
-H "X-API-Key: mesh_your_key_here"
Returns only segments tagged with that topic within the event.
Full-text search
curl "https://api.meshapi.app/v1/segments/search?q=tariffs&limit=50" \
-H "X-API-Key: mesh_your_key_here"
Multi-word queries use AND semantics: q=trade+tariffs matches segments containing both words. Each successful search call counts against your daily search quota.
Search within one segment speaker's transcripts
curl "https://api.meshapi.app/v1/segments/search?q=immigration&segment_speaker_id=381194fe-...&limit=50" \
-H "X-API-Key: mesh_your_key_here"
Combines full-text search with a resolved segment speaker filter.
Search inside an umbrella speaker's events
curl "https://api.meshapi.app/v1/segments/search?q=goal&primary_speaker_id=381194fe-...&limit=50" \
-H "X-API-Key: mesh_your_key_here"
This is the right filter when the selected speaker is an event collection or broadcast group, such as Fox World Cup Announcers.
Search within a topic
curl "https://api.meshapi.app/v1/segments/search?q=sanctions&topic_slug=nato&limit=50" \
-H "X-API-Key: mesh_your_key_here"
Returns segments that match the text query and are tagged with the specified topic.
Search within event type and date range
curl "https://api.meshapi.app/v1/segments/search?q=economy&event_type=remarks&start_date=2026-01-01&end_date=2026-06-01&limit=50" \
-H "X-API-Key: mesh_your_key_here"
Narrows search to a specific event type and time window. All search filters use AND logic.
Check quota usage
curl "https://api.meshapi.app/v1/usage" \
-H "X-API-Key: mesh_your_key_here"
Key fields to watch: daily_transcript_pulls_used vs daily_transcript_pulls_cap, daily_searches_used vs daily_searches_cap, and monthly_transcript_pulls_used vs monthly_transcript_pulls_cap. A _cap of null means unlimited. This endpoint never consumes quota.
Detect updated transcripts
curl "https://api.meshapi.app/v1/pulls?limit=100" \
-H "X-API-Key: mesh_your_key_here"
Returns every transcript you have previously pulled. Check the has_updates field on each entry: true means Mesh has newer transcript data since your last pull (re-diarized, speaker resolved, etc.). Re-fetch those transcripts to get the latest version. This endpoint never consumes quota.
These examples chain multiple endpoints together for real-world data collection tasks. They are written in Python for readability but the logic applies to any HTTP client. Enterprise users with contract-defined caps can adjust concurrency and batch sizes to match their quotas.
Bulk-pull all transcripts for a speaker (using batch endpoint)
Collect a speaker's event IDs, then use the batch endpoint to pull transcripts in chunks of up to 25 (enterprise) or 10 (other plans) per request.
import requests
BASE = "https://api.meshapi.app"
HEADERS = {"X-API-Key": "mesh_your_key_here"}
SPEAKER_ID = "381194fe-4856-4945-9e49-9809be82e924"
# 1. Collect every event ID for this speaker
event_ids = []
cursor = None
while True:
params = {
"speaker_id": SPEAKER_ID,
"has_transcript": "true",
"limit": 200,
}
if cursor:
params["cursor"] = cursor
resp = requests.get(f"{BASE}/v1/events", headers=HEADERS, params=params).json()
event_ids.extend(e["event_id"] for e in resp["data"])
cursor = resp.get("next_cursor")
if not cursor:
break
# 2. Batch-pull transcripts (25 at a time for enterprise, 10 for other plans)
BATCH_SIZE = 25
for i in range(0, len(event_ids), BATCH_SIZE):
batch = event_ids[i : i + BATCH_SIZE]
resp = requests.post(
f"{BASE}/v1/events/batch-segments",
headers=HEADERS,
json={"event_ids": batch, "limit_per_event": 500},
).json()
for entry in resp["results"]:
print(f"{entry['event_id']}: {entry['count']} segments")
for skip in resp["skipped"]:
print(f"Skipped {skip['event_id']}: {skip['reason']}")
if resp["pulls_remaining_daily"] == 0:
print("Daily cap reached — resume tomorrow")
break
Each event returning 50 or more segments counts as one transcript pull per UTC day. Re-fetching the same billable event later in the day costs no additional pull. The batch response tells you how many pulls remain.
Pull transcripts for two speakers and merge by date
Use speaker_ids to fetch events from both speakers in a single paginated call, then batch-pull the transcripts.
SPEAKER_A = "381194fe-4856-4945-9e49-9809be82e924"
SPEAKER_B = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
# 1. Fetch events for both speakers in one call using speaker_ids
events = []
cursor = None
while True:
params = {
"speaker_ids": f"{SPEAKER_A},{SPEAKER_B}",
"has_transcript": "true",
"limit": 200,
}
if cursor:
params["cursor"] = cursor
resp = requests.get(f"{BASE}/v1/events", headers=HEADERS, params=params).json()
events.extend(resp["data"])
cursor = resp.get("next_cursor")
if not cursor:
break
# Events come sorted by date (newest first) — already interleaved
event_ids = [e["event_id"] for e in events]
# 2. Batch-pull transcripts
BATCH_SIZE = 25
for i in range(0, len(event_ids), BATCH_SIZE):
batch = event_ids[i : i + BATCH_SIZE]
resp = requests.post(
f"{BASE}/v1/events/batch-segments",
headers=HEADERS,
json={"event_ids": batch, "limit_per_event": 500},
).json()
for entry in resp["results"]:
event = next(e for e in events if e["event_id"] == entry["event_id"])
speaker = event.get("primary_speaker_name", "Unknown")
print(f"[{speaker}] {event['canonical_title']}: {entry['count']} segments")
if resp["pulls_remaining_daily"] == 0:
break
Quota-aware bulk pulling
The batch endpoint returns pulls_remaining_daily and pulls_remaining_monthly in every response, so you can make cap-aware decisions without extra API calls. For finer control, check GET /v1/usage before starting.
def get_remaining_pulls():
usage = requests.get(f"{BASE}/v1/usage", headers=HEADERS).json()
daily_cap = usage["daily_transcript_pulls_cap"] # null = unlimited
monthly_cap = usage["monthly_transcript_pulls_cap"]
daily_left = (
daily_cap - usage["daily_transcript_pulls_used"]
if daily_cap is not None else float("inf")
)
monthly_left = (
monthly_cap - usage["monthly_transcript_pulls_used"]
if monthly_cap is not None else float("inf")
)
return min(daily_left, monthly_left)
budget = get_remaining_pulls()
print(f"Transcript pulls remaining: {budget}")
# Batch-pull only what fits in the remaining budget
BATCH_SIZE = 25
for i in range(0, len(event_ids), BATCH_SIZE):
batch = event_ids[i : i + BATCH_SIZE]
resp = requests.post(
f"{BASE}/v1/events/batch-segments",
headers=HEADERS,
json={"event_ids": batch},
).json()
for entry in resp["results"]:
print(f"{entry['event_id']}: {entry['count']} segments")
# The batch endpoint gracefully skips events over cap instead of 429-ing
if resp["skipped"]:
for skip in resp["skipped"]:
print(f"Skipped {skip['event_id']}: {skip['reason']}")
break
The usage endpoint never consumes quota. The batch endpoint never returns a 429 for partial over-cap — it processes what it can and skips the rest.
Build a topic corpus from search, then batch-pull full transcripts
Search for segments matching a topic across all speakers, collect the distinct event IDs from the results, then batch-pull the full transcript for each.
# 1. Search for all segments mentioning "tariffs" in press conferences
matched_event_ids = set()
cursor = None
while True:
params = {
"q": "tariffs",
"event_type": "press_conference",
"start_date": "2026-01-01",
"limit": 200,
}
if cursor:
params["cursor"] = cursor
resp = requests.get(
f"{BASE}/v1/segments/search", headers=HEADERS, params=params
).json()
for seg in resp["data"]:
matched_event_ids.add(seg["event_id"])
cursor = resp.get("next_cursor")
if not cursor:
break
print(f"Found segments in {len(matched_event_ids)} events")
# 2. Batch-pull the full transcript for each discovered event
event_list = list(matched_event_ids)
BATCH_SIZE = 25
for i in range(0, len(event_list), BATCH_SIZE):
batch = event_list[i : i + BATCH_SIZE]
resp = requests.post(
f"{BASE}/v1/events/batch-segments",
headers=HEADERS,
json={"event_ids": batch, "limit_per_event": 500},
).json()
for entry in resp["results"]:
print(f"{entry['event_id']}: {entry['count']} segments")
if resp["pulls_remaining_daily"] == 0:
break
Search calls count against the daily search quota, and each new event returning at least 50 segments counts against the transcript pull quota.
Detect and re-pull updated transcripts
Poll GET /v1/pulls to find transcripts that Mesh has re-processed since your last fetch, then batch-pull fresh copies.
# 1. Check for stale pulls
resp = requests.get(f"{BASE}/v1/pulls?limit=100", headers=HEADERS).json()
stale_ids = [p["event_id"] for p in resp["data"] if p.get("has_updates")]
print(f"{len(stale_ids)} transcripts have newer data")
# 2. Batch re-pull only the updated ones
BATCH_SIZE = 25
for i in range(0, len(stale_ids), BATCH_SIZE):
batch = stale_ids[i : i + BATCH_SIZE]
resp = requests.post(
f"{BASE}/v1/events/batch-segments",
headers=HEADERS,
json={"event_ids": batch, "limit_per_event": 500},
).json()
for entry in resp["results"]:
print(f"Refreshed {entry['event_id']}: {entry['count']} segments")
Re-pulling a previously fetched event on the same UTC day does not cost an additional transcript pull.
Extract Q&A from press conferences
Transcript segments include is_question and question_group_id fields. Pull a press conference transcript and separate questions from answers to analyze what journalists are asking a speaker about.
# 1. Find all press conferences for a speaker
events = []
cursor = None
while True:
params = {
"speaker_id": SPEAKER_ID,
"event_type": "press_conference",
"has_transcript": "true",
"limit": 200,
}
if cursor:
params["cursor"] = cursor
resp = requests.get(f"{BASE}/v1/events", headers=HEADERS, params=params).json()
events.extend(resp["data"])
cursor = resp.get("next_cursor")
if not cursor:
break
# 2. Pull each transcript and extract Q&A pairs
for event in events:
resp = requests.post(
f"{BASE}/v1/events/batch-segments",
headers=HEADERS,
json={"event_ids": [event["event_id"]], "limit_per_event": 500},
).json()
if not resp["results"]:
continue
segments = resp["results"][0]["segments"]
questions = [s for s in segments if s["is_question"]]
answers = [s for s in segments if not s["is_question"]]
print(f"{event['canonical_title']}: {len(questions)} questions, {len(answers)} answer segments")
# Group questions by question_group_id to see multi-sentence questions
from collections import defaultdict
groups = defaultdict(list)
for q in questions:
gid = q.get("question_group_id") or q["idx"]
groups[gid].append(q["sentence_txt"])
for gid, texts in groups.items():
print(f" Q: {' '.join(texts)}")
The question_group_id links multi-sentence questions into a single logical question. Segments without is_question in the same region are typically the speaker's answer.
Compare two speakers on a topic
Use the topic segments endpoint (GET /v1/topics/{slug}/segments) with different speaker filters to compare what two speakers say about the same subject. For API keys and hosted MCP, each request counts as a search; Free results follow the same first-15-segments-per-locked-event rule. It does not count as a transcript pull.
SPEAKER_A = "381194fe-4856-4945-9e49-9809be82e924"
SPEAKER_B = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
TOPIC = "nato"
def get_topic_segments(topic_slug, speaker_id):
segments = []
cursor = None
while True:
params = {"speaker_id": speaker_id, "limit": 200}
if cursor:
params["cursor"] = cursor
resp = requests.get(
f"{BASE}/v1/topics/{topic_slug}/segments",
headers=HEADERS, params=params,
).json()
segments.extend(resp["data"])
cursor = resp.get("next_cursor")
if not cursor:
break
return segments
segs_a = get_topic_segments(TOPIC, SPEAKER_A)
segs_b = get_topic_segments(TOPIC, SPEAKER_B)
print(f"Speaker A on {TOPIC}: {len(segs_a)} segments across {len(set(s['event_id'] for s in segs_a))} events")
print(f"Speaker B on {TOPIC}: {len(segs_b)} segments across {len(set(s['event_id'] for s in segs_b))} events")
# Organize by event date for chronological comparison
for seg in sorted(segs_a, key=lambda s: s.get("event_date", "")):
print(f" [{seg.get('event_date', '')[:10]}] {seg['sentence_txt'][:120]}")
This workflow consumes no transcript pulls. API-key and hosted MCP calls to topic segments each consume one daily search.
Correlate transcripts with prediction market outcomes
Pull events that have Kalshi market resolutions, then fetch both the transcript and the resolution data to analyze how speech correlates with market outcomes.
# 1. Find events with transcripts (market-linked events have kalshi_tickers)
events = []
cursor = None
while True:
params = {"has_transcript": "true", "limit": 200}
if cursor:
params["cursor"] = cursor
resp = requests.get(f"{BASE}/v1/events", headers=HEADERS, params=params).json()
events.extend(resp["data"])
cursor = resp.get("next_cursor")
if not cursor:
break
market_events = [e for e in events if e.get("kalshi_tickers")]
print(f"{len(market_events)} events have linked prediction markets")
# 2. For each market-linked event, fetch resolutions and transcript
for event in market_events:
eid = event["event_id"]
# Get market resolutions (unmetered)
resolutions = requests.get(
f"{BASE}/v1/events/{eid}/resolutions", headers=HEADERS
).json()
# Get transcript topics (unmetered)
topics = requests.get(
f"{BASE}/v1/events/{eid}/topics", headers=HEADERS
).json()
print(f"\n{event['canonical_title']}")
print(f" Topics: {', '.join(t['slug'] for t in topics)}")
for r in resolutions.get("resolutions", []):
print(f" Market: {r['market_ticker']} → {r['resolution']}")
# 3. Batch-pull the full transcripts for deeper analysis
event_ids = [e["event_id"] for e in market_events]
BATCH_SIZE = 25
for i in range(0, len(event_ids), BATCH_SIZE):
batch = event_ids[i : i + BATCH_SIZE]
resp = requests.post(
f"{BASE}/v1/events/batch-segments",
headers=HEADERS,
json={"event_ids": batch, "limit_per_event": 500},
).json()
for entry in resp["results"]:
print(f" {entry['event_id']}: {entry['count']} segments pulled")
Resolutions and topics are unmetered. A batch event entry consumes a transcript pull only when it returns at least 50 segments.
Build a speaker profile
Combine speaker details, aggregated stats, event history, and top topics into a comprehensive profile — useful for building speaker pages or research dossiers.
# 1. Speaker identity and stats (unmetered)
speaker = requests.get(
f"{BASE}/v1/speakers/{SPEAKER_ID}", headers=HEADERS
).json()
stats = requests.get(
f"{BASE}/v1/speakers/{SPEAKER_ID}/stats", headers=HEADERS
).json()
print(f"{speaker['canonical_name']} ({speaker['event_count']} events)")
speaking = stats["speaking_time"]
qa = stats["as_primary_speaker"]
print(f" Total speaking time: {speaking['total_speaking_ms'] / 60000:.0f} minutes")
print(f" Events appeared in: {speaking['events_appeared_in']}")
print(f" Q&A events: {qa['qa_event_count']}, avg questions: {qa['avg_questions_per_event']:.1f}")
# 2. All their events (unmetered)
events = requests.get(
f"{BASE}/v1/speakers/{SPEAKER_ID}/events", headers=HEADERS
).json()
# 3. Discover which topics this speaker covers most
from collections import Counter
topic_counts = Counter()
for event in events:
topics = requests.get(
f"{BASE}/v1/events/{event['event_id']}/topics", headers=HEADERS
).json()
for t in topics:
topic_counts[t["slug"]] += 1
print(f"\nTop topics:")
for slug, count in topic_counts.most_common(10):
print(f" {slug}: {count} events")
Every call in this workflow is unmetered — speaker details, stats, events, and event topics all fall outside the transcript pull and search quotas.
Track a topic over time
Use the topic segments endpoint with date ranges to measure how much a topic is discussed week-over-week or month-over-month.
from datetime import date, timedelta
TOPIC = "tariffs"
start = date(2026, 1, 1)
end = date(2026, 6, 1)
# Walk month by month
current = start
while current < end:
month_end = (current.replace(day=28) + timedelta(days=4)).replace(day=1)
if month_end > end:
month_end = end
segments = []
cursor = None
while True:
params = {
"start_date": current.isoformat(),
"end_date": month_end.isoformat(),
"limit": 200,
}
if cursor:
params["cursor"] = cursor
resp = requests.get(
f"{BASE}/v1/topics/{TOPIC}/segments",
headers=HEADERS, params=params,
).json()
segments.extend(resp["data"])
cursor = resp.get("next_cursor")
if not cursor:
break
event_ids = set(s["event_id"] for s in segments)
print(f"{current.strftime('%Y-%m')}: {len(segments)} segments across {len(event_ids)} events")
current = month_end
For API keys and hosted MCP, each topic segment request consumes one daily search. Free results show only the first 15 segments of each locked event, plus full segments from events unlocked that day.
Mesh's MCP server lets compatible AI clients call the same public API used by other Mesh integrations. It offers 37 tools: all 36 authenticated /v1/ operations plus the health check. Requests go to https://api.meshapi.app, so your plan, rate limits, and transcript/search quotas still apply.
Availability: The local server is available from the MeshBackend/api/mesh_mcp/local source package. The hosted server is deployed at https://api.meshapi.app/mcp with browser sign-in. The package has not been published to npm.
In an MCP client that supports remote Streamable HTTP and OAuth, add https://api.meshapi.app/mcp as a remote MCP server. The client opens a Mesh browser sign-in, then shows a consent screen naming the client and describing access to the full Mesh API. Approve only clients you trust. The client handles token refresh; no API key or copied JWT is required. Your account plan and API usage quotas still apply.
The hosted connection can use key-management and paid-plan batch-transcript tools under your signed-in account. It has access to the same API operations as the local server, including operations that create, update, or delete data. The /auth/cli flow remains separate.
mesh_... value when it appears; Mesh only shows it once.MESH_API_KEY in your MCP client's server configuration. Keep the key private and revoke it from the API Keys page if it is exposed.The separate /auth/cli browser flow is for a CLI that listens on localhost:19837. This MCP package does not start that listener, so use the API Keys page for MCP setup.
Install Node.js 18 or newer and, from a MeshBackend/api/mesh_mcp/local source checkout, run:
npm install
Add a local stdio server to your MCP client. Replace the script path with its absolute path on your computer and paste the API key you just created:
{
"mcpServers": {
"mesh": {
"command": "node",
"args": ["/absolute/path/to/MeshBackend/api/mesh_mcp/local/bin/mesh-mcp-server.js"],
"env": {
"MESH_API_KEY": "mesh_your_key_here"
}
}
}
}
On Windows, a path such as C:/Programming/Mesh/MeshBackend/api/mesh_mcp/local/bin/mesh-mcp-server.js works in JSON. Restart your MCP client, then ask it to call get_usage or list_speakers. If the client cannot find node, set command to the absolute path of the Node executable.
To test before configuring a client, run npm run smoke from MeshBackend/api/mesh_mcp/local. It launches the MCP server, checks that all 37 tools are available, and calls the live Mesh health endpoint. If MESH_API_KEY is also set in your shell, it tests authenticated usage and event-type calls. This command makes no account changes and does not consume a search or transcript pull. No MCP deployment is required.
| Area | Tools |
|---|---|
| Events and transcripts | list_events, get_event, get_event_segments, batch_get_segments, get_event_topics, get_event_resolutions, list_event_types |
| Search | search_segments, search_events |
| Speakers and topics | list_speakers, get_speaker, get_speaker_events, get_speaker_children, get_speaker_parents, get_speaker_stats, list_topics, get_topic, get_topic_segments |
| Strike decay | list_series, list_words, resolved_events, list_markets, custom_curves, get_curves |
| Analysis | run_analysis, word_streaks, list_analyses, create_analysis, get_analysis, update_analysis, delete_analysis |
| Account and service | get_usage, list_pulls, list_keys, create_key, revoke_key, health |
Each tool accepts the corresponding API path and query fields as named arguments. For POST and PUT requests, put the JSON request payload in body. For example, search_segments accepts q, filters, limit, and cursor; get_event_segments accepts an event_id, limit, cursor, and optional unlock. Tool results contain the API response JSON, including pagination cursors.
list_markets is the strike-decay series market endpoint; Mesh does not currently expose a general orderbook endpoint through the public API. Strike-decay tools follow the API's Max/Enterprise plan gate, except resolved_events.
For the local server, an API key is enough for data and analysis tools. batch_get_segments requires an API key and is unavailable to Free-plan or JWT-only callers. list_keys, create_key, and revoke_key instead require MESH_ACCESS_TOKEN, a current Supabase user access token. The local server does not obtain or refresh that token. If both values are configured, key-management tools use the user token and other tools use the API key. Most users should manage keys through the API Keys page. The hosted server uses browser authorization instead.
On the Free plan, get_event_segments returns only the first 15 segments of a locked event and includes a preview_notice. Call it with unlock=true to spend one of three account-wide daily unlocks and read the full event. Unlocks are shared with the browser and API keys; fetching the same unlocked event again that UTC day costs no additional unlock. search_segments, search_events, and get_topic_segments show only the first 15 segments of each locked event, plus full results from events unlocked that day. Their preview_notice fields explain this limit. Free previews do not spend unlocks or count as full transcript pulls.
API key and hosted MCP searches share the plan's daily search allowance; each topic-segment request also counts as a search. Use get_usage to check your remaining allowance, and pass returned next_cursor values to continue paginated results. API errors appear as MCP tool errors with the HTTP status and message; 429 responses also include Retry-After when supplied by the API. 401 usually means a missing, invalid, or expired credential. 403 can mean a plan or key-scope restriction.
For paid plans, asking for a word count, searching, running an analysis, or retrieving a short transcript excerpt does not spend a transcript pull. get_event_segments defaults to 49 segments and spends one pull only when it returns 50 or more segments for one event in one response. batch_get_segments applies the same threshold to each event entry. Responses with 1–49 segments do not spend pulls, even across separate pages. A billable event counts once per UTC day and once per billing period for monthly usage. Free-plan users still need to unlock an event to read beyond its first 15 segments.
For a count of how often a word appears, ask the MCP client to use run_analysis with analysis_type: "word_frequency" and count_mode: "occurrences". The default segments mode counts matching segments. Occurrences are case-insensitive text matches and can include a match inside a longer word. This analysis uses neither the search allowance nor transcript pulls; Free-plan analysis is limited to visible preview segments and unlocked events. search_segments finds passages containing the term and spends one daily search, with no transcript pull.
For the full request fields and quota rules, see the REST reference on this page.