Mesh API

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.

Quick start#

curl "https://api.meshapi.app/v1/events?limit=10&has_transcript=true" \
  -H "X-API-Key: mesh_your_key_here"

Authentication#

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.

Plans and quotas#

PoolWhat countsReset
Transcript pullsGET /v1/events/{event_id}/segments or a batch entry returning at least 50 segments for one event; deduped by event per UTC dayDaily and monthly on paid plans
SearchesGET /v1/segments/search, GET /v1/search/events, GET /v1/topics/{slug}/segmentsDaily for API keys and hosted MCP
Other endpointsMetadata, usage, topic listings, speakers, saved analysesUnmetered
PlanDaily transcript pullsDaily searchesMonthly transcript cap
Free3 full-event unlocks/day shared by web, API, and MCP10/day for API/MCPFull access limited by daily unlocks
Trial (14 days)5/day50/day150/month
Pro15/day150/day450/month
Max30/day300/day900/month
EnterpriseContract-definedContract-definedContract-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.

Rate Limits#

In addition to quota caps, all API-key requests are subject to a per-key request-per-minute rate limit:

PlanRequests per minute
Free / Trial / Pro / Max60
Enterprise300

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.

Response format#

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" }

Common errors#

StatusMeaning
400Invalid parameter or request body
401Missing, invalid, or expired credentials
403Account disabled, resource outside key scope, or plan-restricted operation
404Resource not found
409Conflict, such as max active keys reached
422Validation error
429Daily/monthly quota exceeded

Quota errors include useful reset headers when applicable:

  • —Retry-After
  • —X-Pull-Budget-Reset

Speaker identity#

Speaker identity has two layers:

  • —Event speakers describe who an event is attributed to, including umbrella or group speakers such as Fox World Cup Announcers. Use primary_speaker_id on event endpoints.
  • —Segment speakers describe who actually spoke a transcript segment after diarization and resolution. Use 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.

Endpoints#

Health#

GET /health

Public health check.

{ "status": "ok" }

Events#

GET /v1/events

List events. Use has_transcript=true to browse events with transcript data.

Common query params:

ParamTypeDescription
qstringOptional full-text search on event title
event_typestringEvent type such as remarks, press_conference, rally, interview
primary_speaker_idUUIDFilter by event attribution / primary speaker
primary_speaker_idsstringComma-separated UUIDs (max 20). Returns events where ANY listed speaker is primary.
segment_speaker_idUUIDFilter to events where this resolved speaker appears in transcript segments
segment_speaker_idsstringComma-separated resolved segment speaker UUIDs
speaker_idUUIDLegacy alias for primary_speaker_id
speaker_idsstringLegacy alias for primary_speaker_ids
topic_slugstringFilter by topic
citystringPartial city match
state_codestringExact state code
start_datedateEvents on or after this date
end_datedateEvents on or before this date
updated_afterdatetimeIncremental sync watermark. Returns only events with updated_at > updated_after.
sortstringevent_date_desc (default), event_date_asc, speaker_asc, event_title_asc, relevance
includestringComma-separated optional expansions. Use event_speakers for curated participant assignments and/or segment_speakers for resolved transcript speaker summaries.
limitintPage size, default 50
cursorstringCursor 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:

ParamTypeDescription
limitintPage size, default 49; 1–49 returned segments do not spend a paid-plan pull
cursorstringCursor from previous response
segment_speaker_idUUIDFilter to one resolved segment speaker
speaker_idUUIDLegacy alias for segment_speaker_id
topic_slugstringFilter to one topic
unlockbooleanFree-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
}
FieldTypeDescription
event_idsUUID[]Event UUIDs to pull transcripts for. Max 25 (enterprise) or 10 (other plans).
limit_per_eventintMax 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.

Event Types#

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:

ParamTypeDescription
qstringFull-text segment search
segment_speaker_idUUIDFilter by resolved segment speaker
primary_speaker_idUUIDConstrain search to events attributed to this primary speaker
speaker_expandstringSet to children to expand segment_speaker_id through speaker relationships
speaker_idUUIDLegacy alias for segment_speaker_id
topic_slugstringFilter by topic
event_typestringFilter by event type
start_datedateEvent start date lower bound
end_datedateEvent start date upper bound
sortstringrelevance (default), event_date_desc, event_date_asc, speaker_asc, event_title_asc
limitintPage size
cursorstringCursor 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:

ParamTypeDescription
qstringOptional search text used for title and transcript matching
event_idUUIDOptional single-event scope
event_typestringFilter by event type
primary_speaker_idUUIDFilter by event primary speaker
segment_speaker_idUUIDFilter by resolved segment speaker
speaker_expandstringSet to children to expand speaker/group filters
speaker_idUUIDLegacy alias for segment_speaker_id
topic_slugstringFilter by topic slug
start_datedateEvent start date lower bound
end_datedateEvent start date upper bound
has_transcriptbooleantrue returns events with transcript data only; use this for transcript-backed All-mode results
sortstringrelevance (default), event_date_desc, event_date_asc, speaker_asc, event_title_asc
limitintPage size
cursorstringCursor 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_match
  • —matching_segment_count (visibility-filtered for Free plan)
  • —best_snippet, best_snippet_start_time_ms, best_snippet_idx, best_snippet_segment_id
  • —topics: string[] of canonical event-topic slugs
  • —speakers: string[] of canonical event-attribution speaker names
  • —matched_segment_speakers: string[] of canonical resolved-speaker names on visible transcript matches
  • —num_questions, starts_at, event_type

Event-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.

Speakers#

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.

Topics#

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.

Usage#

GET /v1/usage

Return your current plan, daily transcript pulls, daily searches, monthly transcript usage, and trial metadata. Does not consume quota.

Important fields:

FieldDescription
planCurrent effective plan
daily_transcript_pulls_used / daily_transcript_pulls_capTranscript pull usage today
daily_searches_used / daily_searches_capSearch usage today
monthly_transcript_pulls_used / monthly_transcript_pulls_capMonthly transcript ceiling
trial_started_at / trial_ends_atTrial metadata, if applicable

Pull History#

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:

ParamTypeDescription
limitintPage size
offsetintOffset pagination value
api_key_idUUIDOptional key-specific history filter

Use has_updates to show stale transcript pulls in a user dashboard.

API Keys#

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.

Analyses#

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.

Workflows#

Browse and Discover Events#

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:

  • —Keep updated_after fixed across pages.
  • —Pass the returned next_cursor until it is null.
  • —Deduplicate by 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 Transcripts#

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.

Search Across Events#

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.

Monitor Usage and Changes#

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.

Combined Workflows#

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.

Notes#

  • —Search results are ordered by transcript position, not relevance.
  • —Free-plan unlocks reset at 00:00 UTC.
  • —The API key value is only visible once at creation. Store it immediately.
  • —Caps are account-wide across all your API keys.

MCP Server#

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.

Hosted connection#

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.

Sign in and create an API key#

  1. —Sign in to Mesh in your browser. Complete onboarding if prompted.
  2. —Open API Keys and create a key. Copy the full mesh_... value when it appears; Mesh only shows it once.
  3. —Add the key as 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 and connect#

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.

What the tools cover#

AreaTools
Events and transcriptslist_events, get_event, get_event_segments, batch_get_segments, get_event_topics, get_event_resolutions, list_event_types
Searchsearch_segments, search_events
Speakers and topicslist_speakers, get_speaker, get_speaker_events, get_speaker_children, get_speaker_parents, get_speaker_stats, list_topics, get_topic, get_topic_segments
Strike decaylist_series, list_words, resolved_events, list_markets, custom_curves, get_curves
Analysisrun_analysis, word_streaks, list_analyses, create_analysis, get_analysis, update_analysis, delete_analysis
Account and serviceget_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.

Credentials, quotas, and errors#

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.