# Particle API

> Podcast intelligence — podcasts, episodes, transcripts, guests, chart rankings, advertising, listener ratings, and political-bias and brand-suitability analytics — alongside company and people data and a topic taxonomy, exposed as one connected knowledge graph through a REST API and an MCP server.
## Instructions for LLM agents

These conventions are load-bearing, and a page index alone hides them:

- **Pick the right surface.** Building an agent loop (Claude Code, Cursor, Codex, ChatGPT, a custom MCP client)? Use the MCP server at `https://mcp.particle.pro` — slug-first inputs, bundled responses, markdown output. Building a service (server-to-server, scheduled jobs)? Use the REST API at `https://api.particle.pro` with an API key — typed JSON, OpenAPI schema. Building a frontend? Route calls through your own backend so the API key stays server-side — never embed keys in browser or mobile code. Connecting a client for someone? Follow `https://api.particle.pro/agents.md`. The endpoint and tool map with per-call prices is `https://api.particle.pro/llms.txt`.
- **No API key? Pay per request.** Every billable REST endpoint and `POST /mcp` accept an x402 USDC micropayment (Base) in place of a credential: a keyless call returns `402` with the payment requirements in the `PAYMENT-REQUIRED` header; sign the transfer and retry with `PAYMENT-SIGNATURE`, and the receipt comes back in `PAYMENT-RESPONSE`. Each REST call and each MCP `tools/call` costs its per-call price, a whole number of cents from $0.01 (MCP `initialize` and `tools/list` are free, and `particle_catalog` lists every tool with its price); a request whose every call fails is never charged, while a batch with any successful call settles in full. Free endpoints stay free; alerts and enterprise surfaces still need an account. Sending any credential — even an invalid one — takes the normal auth path instead. Discovery: `/.well-known/x402.json` on api.particle.pro and mcp.particle.pro lists the payable endpoints and terms, and every payable MCP tool with its per-call price under `mcp.tools`; the `/.well-known/x402` manifest on each host lists that host's own resources, so only the MCP host's carries the per-tool list; every payable operation in https://api.particle.pro/openapi.json carries `x-payment-info` and a `402` response; each 402 carries a Bazaar declaration, so the endpoints are searchable in the Coinbase x402 Bazaar. See https://docs.particle.pro/x402.md.
- **Tools are lean by default and expand.** Most MCP tools return a minimal payload and opt into richer sections via an `include` array (e.g. a company's people, products, and competitors; a person's roles and podcast appearances) or a `mode`/`format` switch — a tool does far more than its name implies. Check the tool's input schema before assuming a capability is missing.
- **Responses form a graph; slugs are edges.** A slug a tool returns (person, company, podcast, episode, publisher, guest) is a valid input to the other tools. Resolve a free-text name once (`particle_entity_resolve`, `particle_person_resolve`, `particle_company_resolve`, `particle_podcast_resolve`), then traverse: company → its people → a person's podcast appearances → that episode's transcript and the entities named in it. Never guess or fabricate a slug — resolve it. Slugs are short handles Particle assigns, not names slugified: 20VC is `the-twenty-minute-vc`, Lenny's Podcast is `lennys`, All-In is `all-in`. Take them from responses; a constructed slug returns 404, and trying other spellings never resolves it. A podcast slug is not an episode id: list the show's episodes to get one.
- **Choose search by intent.** `particle_podcast_search_transcripts` finds dialogue *about* a topic (semantic, keyword, or hybrid; relevant clips arrive inline on matches). `particle_podcast_find_mentions` finds lines *naming* a resolved entity — a person, company, or any other resolvable slug (places, organizations, events, concepts) — its default `format="summary"` previews the first ~10 mention lines per episode for scanning; call back with `format="detail"` and an `episode_slug` for an episode's complete mention set with context. Both take `format="compact"` for screening many results (a fan-out over companies, themes, or dates) before reading any: a compact search match is its identity rows, segment id, relevance score, and the segment's one-line description, with no dialogue; a compact mentions episode is its mention count, the strings the entity was mentioned as, and the segments carrying the mentions, with no lines. Cite by segment id and read only the survivors. `particle_podcast_list_episodes` is filter-driven episode discovery (podcast, person, company, language, date, duration). Don't put an entity name in `semantic_search` — that's a topic field; resolve the name and pass it as a `person_slug`/`company_slug`/`entity_slug` filter, or use `particle_podcast_find_mentions`. For "how often over time" questions, use `particle_podcast_get_episode_timeseries` instead of paging search or mentions once per period. For "shows like this show", use `particle_podcast_list_related` (add `include: ["basis"]` for the reasons) or `include: ["related"]` on `particle_podcast_resolve` — not a topic or semantic search; for "who else covered this episode", `particle_podcast_list_related_episodes` or `include: ["related"]` on `particle_podcast_get_episode`. For where a guest could appear next, use `include: ["recommended_podcasts"]` on `particle_podcast_get_guest`; for who a show could book, `include: ["recommended_guests"]` on `particle_podcast_resolve`; for advertisers a show could pitch, `include: ["recommended_sponsors"]` on `particle_podcast_resolve` (premium). Within a search, `semantic_search` carries the idea (a sentence, paraphrase-tolerant) while `keyword_search` carries words that must be literally spoken — every word must occur in the same passage, so keep it to one or two exact tokens and never put a sentence there; `keyword_match="ranked"` relaxes it to a relevance hint. Add filters only after a broad query shows the topic has coverage: when filters empty a search, the error names the parameter responsible and the retry to make, so act on it rather than re-issuing variations.
- **Not every episode is transcribed.** Episodes carry `transcript_status`. A show's older episodes, discovered in its feed but not transcribed, are its back catalogue: `particle_podcast_list_episodes` lists them only when you pass `transcript_status` with `podcast_slug`, and they read `requestable`, or `queued` once someone has requested the transcript. An episode without a transcript has no speakers, entities, segments or clips, so its empty lists say nothing about who was on it or what it covered — and counts over a show's episodes cover only its transcribed ones. `include: ["coverage"]` on `particle_podcast_resolve` says how many of a show's episodes exist and how many are transcribed, by year.
- **Most tools are read-only; the `particle_alert_*` tools are the writable exception.** They create and manage alerts that each watch a single entity for podcast mentions or speaker appearances, and they act on the one project your credential is scoped to — no project parameter, no way to reach another project's alerts. Resolve a name to a slug, optionally preview match frequency with `particle_alert_preview`, then `particle_alert_create` to start watching it. When a name has no slug, or its entity has no podcast coverage, watch the phrase instead: `kind: "KEYWORD_MENTION"` with `keyword` in place of `entities`, and a `description` saying what the phrase means. Alerts accept a persistent `filters` object on create and update — narrow what gets surfaced by language, relevance (`EVERYTHING`|`RELEVANT`), source popularity (`ANY`|`POPULAR`), and (for `PODCAST_SPEAKER` alerts) `speaker_roles`. `particle_alert_create`/`particle_alert_update` mutate and `particle_alert_delete` is a destructive soft delete.
- **Discovery is free; execution is metered.** Discovery methods (`initialize`, `tools/list`, `resources/list`, `resources/read`, `prompts/list`, `ping`) and tools marked free are intentionally served without authentication; every metered `tools/call` requires an OAuth bearer, a `pp_` API key, or an x402 payment. A bare connection advertises the default categories, but every public tool is callable by name. `particle_catalog` (free) lists every category and tool with expand options, plus full input schemas per category; opt-in categories advertise on `tools/list` via the MCP URL, e.g. `?include=podcast_advertising,podcast_publishers,podcast_ratings,podcast_bias,podcast_suitability` (use these canonical tokens — unknown values are silently ignored).
- **Errors course-correct.** Tool errors lead with a stable `**Error code:** <slug>` line and a suggestion naming the next call (404 → re-resolve the slug; 400/422 → check the schema via `particle_catalog`). REST errors are RFC 9457 `application/problem+json` with a stable `error_code` and, when there is a self-service fix, a `resolve` object naming the action, URL, method, and endpoint; a 404 on a slug means re-resolve it, a 422 names the parameter at fault, and a 429 carries `Retry-After`. Follow the suggestion instead of blind-retrying, and never retry-loop an `internal_error`.
- **Reading these docs?** Append `.md` to any docs URL for raw markdown (e.g. `https://docs.particle.pro/mcp/overview.md`), fetch the entire corpus from `https://docs.particle.pro/llms-full.txt`, or start from the page index at `https://docs.particle.pro/llms.txt`.

- **Render selected evidence only when a visual helps.** After retrieving Particle data, call `particle_radar_render_cards` directly with a title and up to six episode, podcast, company, or person cards. Use only evidence and canonical HTTPS source URLs returned by the data tools; do not invent links or pass credentials. The opt-in `radar` category (also in `include=all`) is free presentation, with no data fetch or storage. The renderer owns an MCP Apps UI resource and returns structured cards plus a complete Markdown fallback. Other data tools keep their existing output formats; `particle_call` provides the renderer's text fallback only.
## Guides: Getting started

- [Particle API](https://docs.particle.pro/index.md): Inside every podcast: transcripts, speakers, entities, sponsors, and a knowledge graph that connects people and companies across episodes.
- [Quickstart](https://docs.particle.pro/quickstart.md): Trace one person across podcasts, dialogue, and companies in five minutes.
- [Agent onboarding](https://docs.particle.pro/agents.md): The setup playbook an agent follows to connect a client to Particle over MCP, the REST API, x402, or MPP, and run a first live query. Served raw at api.particle.pro/agents.md.
- [Concepts](https://docs.particle.pro/concepts.md): Cross-cutting conventions: IDs, pagination, errors, pricing weight, and choosing the right endpoint.
- [Coverage](https://docs.particle.pro/coverage.md): What is in the catalog, how fresh it is, what every episode carries, and the calls that tell you exactly what is available for a show, an episode, or a language before you build on it.
- [Agent authentication](https://docs.particle.pro/auth.md): The auth.md agent-onboarding recipe — discovery, the credential decision tree, registration, usage, errors, and revocation — for agents connecting to Particle Pro.
- [Pay per request with x402](https://docs.particle.pro/x402.md): Call any billable Particle Pro endpoint without an account by paying per request in USDC over the x402 protocol — what the 402 challenge carries, what a call costs, and how an agent pays.
- [Pay per request with MPP](https://docs.particle.pro/mpp.md): Use USDC on Base to pay for Particle API requests with the Machine Payments Protocol, alongside x402.
- [Changelog](https://docs.particle.pro/changelog.md): What's new on the Particle Pro REST API — new endpoints and capabilities, and anything that could affect an existing integration.
## Guides: Recipes

- [Paginate through everything](https://docs.particle.pro/recipes/pagination.md): How cursor pagination works on every list endpoint: the envelope, the loop that fetches every page in curl, JavaScript, and Python, what limit means, and which endpoints paginate.
- [Track a company across podcasts](https://docs.particle.pro/recipes/track-a-company.md): Resolve a company once, read every line that names it, chart how often it comes up week by week, then hand the watching to an alert with a webhook.
- [Find the most quotable moments on a topic](https://docs.particle.pro/recipes/quotable-moments.md): Search dialogue by meaning, take the highlight clips that arrive with each match, then pull the strongest clips on a speaker or a show, each with playable audio.
- [From an empty page to the data](https://docs.particle.pro/recipes/empty-results.md): Three checks that turn an empty data array into the call that returns what you were looking for: confirm the subject is in the catalog, confirm it has dialogue, then narrow one filter at a time.
- [Handle errors and retries](https://docs.particle.pro/recipes/handle-errors.md): What each status means on this API, which responses to retry and which never to, and a retry wrapper that reads error_code and Retry-After instead of guessing.
## Guides: Podcasts

- [Podcasts](https://docs.particle.pro/podcasts/overview.md): What's inside every episode — transcripts, speakers, segments, clips, sponsors, and bias.
- [Search](https://docs.particle.pro/podcasts/search.md): Find a podcast by name. Forgiving, typo-tolerant ranked search over the catalog, with a match_quality signal on every result.
- [Episode search](https://docs.particle.pro/podcasts/episode-search.md): Search inside podcast episodes by what is said — by meaning, by exact phrase, or both. For 'every line about a person or company', see Mentions.
- [Mentions](https://docs.particle.pro/podcasts/mentions.md): Every line of dialogue where a person or company is named, grouped by episode. The right endpoint for read-everything-about-X workflows.
- [Entity Charts](https://docs.particle.pro/podcasts/entity-charts.md): Daily Top-N charts of what podcasts talk about — TV series, movies, and video games ranked by the distinct shows that mentioned them, the players, teams, and coaches of thirteen sports and leagues, guests ranked by the shows they appeared on, and composites for entertainment, sports, and a wider curated pool of entity types — each entry with its movement since the previous edition, and, where warranted, a quote-backed explanation of the move.
- [Guests](https://docs.particle.pro/podcasts/guests.md): Track the people who appear on podcasts — lifetime profiles, every appearance, the shows they join, who's doing the rounds, and brand-suitability exposure.
- [Related Podcasts](https://docs.particle.pro/podcasts/related.md): Shows related to a given show — ranked by content, topics, shared guests, network and sponsors — with the reasons attached.
- [Related Episodes](https://docs.particle.pro/podcasts/related-episodes.md): Episodes from other shows that cover the same story or subject as a given episode, ranked by content, shared entities, shared topics and a shared story — with the reasons attached.
- [Format Profile](https://docs.particle.pro/podcasts/format.md): What kind of show each podcast is — guest frequency, detected formats (interview, panel, call-in, solo), ads, video, episode length, and publishing cadence — as filterable attributes.
- [Episodes](https://docs.particle.pro/podcasts/episodes.md): Discover and filter episodes across the catalog, with rich per-episode sub-resources.
- [Episode feed (polling)](https://docs.particle.pro/podcasts/feed.md): Resumable, strictly-ordered polling for newly ingested episodes — the all-plans alternative to the real-time stream.
- [Episode stream (firehose)](https://docs.particle.pro/podcasts/stream.md): Real-time Server-Sent Events firehose that pushes podcast episodes to you as they are ingested.
- [Episode archive](https://docs.particle.pro/podcasts/archive.md): Bulk download of every transcribed podcast episode, kept current daily, for loading our full history before following the stream.
- [Transcripts](https://docs.particle.pro/podcasts/transcripts.md): Diarized dialogue, word-level timestamps, entity mentions in context, and SRT export.
- [Segments & clips](https://docs.particle.pro/podcasts/segments-and-clips.md): AI-identified structural sections of every episode and engagement-scored highlight clips.
- [Advertising](https://docs.particle.pro/podcasts/advertising.md): Sponsor analytics across the podcast catalog: leaderboards, per-company presence, and co-occurrence.
- [Brand Suitability](https://docs.particle.pro/podcasts/suitability.md): Industry-standard content risk and advertiser-fit assessment for podcasts: per-category prevalence and treatment, evidence excerpts, and a deterministic trend across analyses.
- [External links](https://docs.particle.pro/podcasts/external-links.md): Every third-party platform on which a podcast has a presence — directories, social profiles, video channels, websites — with resolved URLs and per-platform metadata.
- [Lookup by external identifier](https://docs.particle.pro/podcasts/lookup.md): Resolve Apple, Spotify, YouTube, and other platform identifiers to Particle podcasts — deterministically, in bulk, with each result echoing the input you sent.
- [Publishers](https://docs.particle.pro/podcasts/publishers.md): Browse the organizations behind the podcasts — Goalhanger, iHeartPodcasts, BBC Radio 4 — and pivot from a publisher to its full catalog.
- [Publisher advertising](https://docs.particle.pro/podcasts/publishers-advertising.md): Roll up ads, sponsors, and bundle-buy intelligence across every podcast a publisher owns — iHeartPodcasts, NPR, Wondery, Bloomberg, and the rest.
- [Podcast Publisher Bias](https://docs.particle.pro/podcasts/publishers-bias.md): Aggregate political bias intelligence at the podcast publisher level: catalog-wide lean, diversity, regional distribution, and cross-publisher rankings.
- [Publisher Brand Suitability](https://docs.particle.pro/podcasts/publisher-suitability.md): Publisher-level rollups of IAB Tech Lab Brand Safety & Suitability Framework verdicts — tier composition, per-category exposure, cross-publisher leaderboards, and category-pivot views for regulated brands.
- [Rankings](https://docs.particle.pro/podcasts/rankings.md): Browse the live Apple and Spotify podcast charts — top podcasts by country and category, per-podcast chart presence, historical snapshots, and trending movers.
- [Ratings & reviews](https://docs.particle.pro/podcasts/ratings.md): Per-podcast user-generated 1–5 star ratings and review text, a numeric aggregate per (platform, locale), and a periodic narrative summary of listener sentiment.
## Guides: Companies

- [Companies](https://docs.particle.pro/companies/overview.md): Cross-referenced company profiles with SEC, Wikidata, ticker, domain, and knowledge-graph identifiers.
- [External links](https://docs.particle.pro/companies/external-links.md): Every third-party identifier a company carries — LinkedIn, social profiles, its registrable domain, stock tickers, SEC CIK, and Wikidata QID — in one normalized shape.
- [Products](https://docs.particle.pro/companies/products.md): Three-level product hierarchies with lifecycle status.
## Guides: Knowledge graph

- [Entities](https://docs.particle.pro/knowledge-graph/entities.md): People, organizations, places, and concepts — the connective tissue across audio and structured data.
- [Look up people and companies by identifier](https://docs.particle.pro/entities/lookup.md): Resolve a LinkedIn slug, social handle, company domain, ticker, CIK, or Wikidata QID to the people and companies that carry it — in bulk, with each result echoing the input you sent.
- [Topics](https://docs.particle.pro/knowledge-graph/topics.md): Hierarchical topic taxonomy used to classify episodes.
## Guides: Alerts

- [Alerts](https://docs.particle.pro/alerts/overview.md): Get notified whenever a person, company, topic, or keyword you care about is mentioned — or shows up as a speaker — on a podcast.
- [Create and manage alerts](https://docs.particle.pro/alerts/create.md): Resolve an entity, preview how often an alert would fire, create it, and update or pause it later — from the dashboard or the API.
- [Alert results](https://docs.particle.pro/alerts/results.md): Read the matches an alert detects, the emails it sends, and the shareable pages behind every result.
- [Deliver alerts to Slack](https://docs.particle.pro/alerts/slack.md): Post alert matches to a Slack channel: connect a workspace, attach a channel to an alert, and see what the message looks like.
- [Deliver alerts to a webhook](https://docs.particle.pro/alerts/webhooks.md): Receive alert matches as signed JSON POSTs: create a webhook connection, attach it to an alert, verify the signature, and handle the payload.
## Guides: Account

- [Zero data retention](https://docs.particle.pro/account/data-retention.md): What Particle keeps from your organization's API and MCP requests, what zero data retention removes, what it does not cover, and how to request it.
## Guides: Errors

- [Error reference](https://docs.particle.pro/errors/overview.md): Structured error responses and how to handle them
## Guides: Errors › Billing & subscription

- [no_active_plan](https://docs.particle.pro/errors/no_active_plan.md): No active billing plan
- [billing_info_required](https://docs.particle.pro/errors/billing_info_required.md): Billing information is required for paid plans
- [plan_required](https://docs.particle.pro/errors/plan_required.md): A billing plan is required to create projects
- [payment_past_due](https://docs.particle.pro/errors/payment_past_due.md): Reserved for a past-due subscription payment; not returned today
- [payment_delinquent](https://docs.particle.pro/errors/payment_delinquent.md): The subscription is delinquent after failed payments
- [subscription_suspended](https://docs.particle.pro/errors/subscription_suspended.md): Subscription suspended due to non-payment
- [subscription_inactive](https://docs.particle.pro/errors/subscription_inactive.md): Subscription is not active
- [subscription_not_found](https://docs.particle.pro/errors/subscription_not_found.md): Billing subscription not found
- [no_active_subscription](https://docs.particle.pro/errors/no_active_subscription.md): No active subscription for spend limit configuration
- [billing_unavailable](https://docs.particle.pro/errors/billing_unavailable.md): Billing details are temporarily unavailable
- [plan_not_selected](https://docs.particle.pro/errors/plan_not_selected.md): Organization has no active plan selected
- [plan_not_available](https://docs.particle.pro/errors/plan_not_available.md): The requested plan is deprecated and not available for new subscriptions
- [plan_does_not_support_overage_usage](https://docs.particle.pro/errors/plan_does_not_support_overage_usage.md): The current plan does not support overage usage configuration
- [subscription_canceled](https://docs.particle.pro/errors/subscription_canceled.md): Subscription has been canceled
- [subscription_already_canceled](https://docs.particle.pro/errors/subscription_already_canceled.md): Subscription is already canceled — sign up again to reactivate
- [trial_ended](https://docs.particle.pro/errors/trial_ended.md): Trial ended — choose a paid plan to continue
- [endpoint_not_in_plan](https://docs.particle.pro/errors/endpoint_not_in_plan.md): This endpoint or tool is not included in your current plan
- [subscription_not_canceled](https://docs.particle.pro/errors/subscription_not_canceled.md): Subscription is not in the canceled state, so it cannot be resumed
- [cancellation_revertable](https://docs.particle.pro/errors/cancellation_revertable.md): Subscription is canceled but the cancellation has not yet taken effect — resume to undo it
- [cancellation_effective](https://docs.particle.pro/errors/cancellation_effective.md): Cancellation has already taken effect — the Orb subscription is gone, so resume is not possible
- [plan_change_blocked](https://docs.particle.pro/errors/plan_change_blocked.md): Plan change cannot be applied because current usage exceeds the target plan's allowance
- [pending_plan_change_exists](https://docs.particle.pro/errors/pending_plan_change_exists.md): Operation blocked because a deferred plan change is scheduled to take effect at end-of-term
- [promo_code_invalid](https://docs.particle.pro/errors/promo_code_invalid.md): The promo code does not exist or is no longer active
- [promo_code_already_redeemed](https://docs.particle.pro/errors/promo_code_already_redeemed.md): This organization has already redeemed this promo code
- [promo_code_already_active](https://docs.particle.pro/errors/promo_code_already_active.md): A promo code is already active on this subscription
- [promo_code_not_valid_for_plan](https://docs.particle.pro/errors/promo_code_not_valid_for_plan.md): The promo code is restricted to specific plans
- [promo_code_requires_paid_plan](https://docs.particle.pro/errors/promo_code_requires_paid_plan.md): Promo codes can only be applied to paid plans
- [promo_code_exhausted](https://docs.particle.pro/errors/promo_code_exhausted.md): The promo code has reached its redemption limit
- [promo_code_signup_only](https://docs.particle.pro/errors/promo_code_signup_only.md): The promo code can only be applied during signup
- [paid_plan_confirmation_required](https://docs.particle.pro/errors/paid_plan_confirmation_required.md): Content reserved for paying subscribers was requested by a signed-in session without an active paid plan — one still in its credit phase, or one with no plan that includes Radar
## Guides: Errors › Usage limits

- [spend_limit_exceeded](https://docs.particle.pro/errors/spend_limit_exceeded.md): Monthly spend limit exceeded
- [credits_depleted](https://docs.particle.pro/errors/credits_depleted.md): Credit allocation exhausted for this billing period
- [rate_limit_exceeded](https://docs.particle.pro/errors/rate_limit_exceeded.md): API rate limit exceeded
- [seat_limit_exceeded](https://docs.particle.pro/errors/seat_limit_exceeded.md): Organization has reached the seat cap for its plan
- [add_on_required](https://docs.particle.pro/errors/add_on_required.md): Feature requires purchasing an add-on package
- [plan_does_not_support_alerts](https://docs.particle.pro/errors/plan_does_not_support_alerts.md): The organization's plan does not include the alerts feature
## Guides: Errors › Authentication & authorization

- [auth_required](https://docs.particle.pro/errors/auth_required.md): Authentication required
- [api_key_required](https://docs.particle.pro/errors/api_key_required.md): Valid API key required
- [payment_required](https://docs.particle.pro/errors/payment_required.md): The request had no credential and the endpoint is billable — pay per request with x402 or authenticate with an API key
- [pro_required](https://docs.particle.pro/errors/pro_required.md): Pro subscription required
- [premium_required](https://docs.particle.pro/errors/premium_required.md): Endpoint or tool requires a plan that includes premium endpoints
- [enterprise_required](https://docs.particle.pro/errors/enterprise_required.md): Endpoint is available only to organizations on the Enterprise plan
- [episode_archive_not_enabled](https://docs.particle.pro/errors/episode_archive_not_enabled.md): The podcast episode archive is not enabled for this organization
- [not_a_member](https://docs.particle.pro/errors/not_a_member.md): Not a member of the organization
## Guides: Errors › Account

- [email_exists](https://docs.particle.pro/errors/email_exists.md): Account already exists with this email
- [token_invalid](https://docs.particle.pro/errors/token_invalid.md): Invalid or expired reset token
- [token_expired](https://docs.particle.pro/errors/token_expired.md): Reset token has expired or already been used
- [social_login_only](https://docs.particle.pro/errors/social_login_only.md): Account uses social login
- [invite_expired](https://docs.particle.pro/errors/invite_expired.md): Organization invitation has expired
- [email_verification_required](https://docs.particle.pro/errors/email_verification_required.md): Email verification is required to complete registration
- [account_owns_paid_organization](https://docs.particle.pro/errors/account_owns_paid_organization.md): Account owns an organization that has a plan
- [account_sole_owner_with_members](https://docs.particle.pro/errors/account_sole_owner_with_members.md): Account is the only owner of an organization with other members
## Guides: Errors › Podcast transcription

- [transcript_not_available](https://docs.particle.pro/errors/transcript_not_available.md): The episode was discovered in its podcast's back catalogue and has not been transcribed.
- [episode_audio_unavailable](https://docs.particle.pro/errors/episode_audio_unavailable.md): The episode's audio cannot be fetched, so it cannot be transcribed.
## Guides: Errors › Alert notifications

- [notification_email_in_use](https://docs.particle.pro/errors/notification_email_in_use.md): The notification email is still referenced by one or more alerts
## Guides: Errors › Generic

- [bad_request](https://docs.particle.pro/errors/bad_request.md): Malformed request
- [validation_error](https://docs.particle.pro/errors/validation_error.md): Request body or parameters failed validation
- [unresolved_reference](https://docs.particle.pro/errors/unresolved_reference.md): A name or identifier in the request does not match anything.
- [not_found](https://docs.particle.pro/errors/not_found.md): Resource not found
- [conflict](https://docs.particle.pro/errors/conflict.md): Request conflicts with current state
- [forbidden](https://docs.particle.pro/errors/forbidden.md): Access denied
- [internal_error](https://docs.particle.pro/errors/internal_error.md): Unexpected server error
- [request_timeout](https://docs.particle.pro/errors/request_timeout.md): The request exceeded the server time limit
## Guides: Errors › Internal

- [feature_check_failed](https://docs.particle.pro/errors/feature_check_failed.md): Feature availability check failed
## API reference: API documentation

- [Introduction](https://docs.particle.pro/api-reference/introduction.md): Particle API reference — base URL, authentication, and machine-readable specs.
- [Alerts](https://docs.particle.pro/api-reference/alerts.md): Watch people, companies, and topics across the podcast catalog and get notified by email whenever one is mentioned or appears as a speaker.
- Every endpoint page is generated from the OpenAPI document at https://api.particle.pro/openapi.json; the endpoint and tool map with per-call prices is https://api.particle.pro/llms.txt
## MCP server: Get started

- [Particle Pro MCP server](https://docs.particle.pro/mcp/overview.md): An OAuth-secured MCP server that exposes Particle's podcast, knowledge graph, company, and advertising surfaces as tool calls for AI agents.
- [Quickstart](https://docs.particle.pro/mcp/quickstart.md): Connect the Particle Pro MCP server to Claude Code, Claude Desktop, Cursor, VS Code, Codex, ChatGPT, Windsurf, Zed, the Python MCP SDK, an LLM API, or a custom MCP client.
- [Skill bundles](https://docs.particle.pro/mcp/skills.md): Pre-built agent skills — a curated tool URL plus a copy-paste SKILL.md — for the three workflows people run most.
- [Tool sets & discovery](https://docs.particle.pro/mcp/tool-sets.md): How Particle tools are grouped into exposure categories, how the include/exclude selectors shape your tools/list, and why every public tool stays callable by name.
- [Authentication](https://docs.particle.pro/mcp/authentication.md): OAuth 2.1 for interactive clients — discovery, dynamic client registration, PKCE, refresh, revocation — and API-key bearer auth for headless agents.
- [Errors](https://docs.particle.pro/mcp/errors.md): How tool errors surface in MCP responses, and how the REST error catalog maps onto them.
- [Changelog](https://docs.particle.pro/mcp/changelog.md): What's new on the Particle Pro MCP server — new tools and capabilities, and anything that changes how your agent connects or calls.
## MCP server: Tools

- [Tool reference](https://docs.particle.pro/mcp/tools/overview.md): Every tool the Particle Pro MCP server exposes, grouped by exposure category.
## MCP server: Tools › System

- [particle_catalog](https://docs.particle.pro/mcp/tools/system/catalog.md): Browse the full Particle tool catalog — every exposure category, its tools, and (with a category) full input schemas.
- [particle_call](https://docs.particle.pro/mcp/tools/system/call.md): Dispatch any public Particle tool by name — a compatibility fallback for harnesses that block un-advertised tools.
## MCP server: Tools › Radar cards

- [particle_radar_render_cards](https://docs.particle.pro/mcp/tools/radar/radar-render-cards.md): Display selected Particle research results as embedded Radar cards, with source links and a Markdown fallback.
## MCP server: Tools › Podcasts

- [particle_podcast_resolve](https://docs.particle.pro/mcp/tools/podcasts/podcast-resolve.md): Find a podcast by title, slug, iTunes ID, or RSS URL; returns slug, episode count, bias, speakers, and optional hydrations.
- [particle_podcast_get_episode](https://docs.particle.pro/mcp/tools/podcasts/podcast-get-episode.md): Bundled overview of one episode — speakers, top entities, segment/clip counts, and optional transcript, segments, entities, clips, and topics.
- [particle_podcast_find_mentions](https://docs.particle.pro/mcp/tools/podcasts/podcast-find-mentions.md): Find dialogue lines where a specific person or company is named in podcast transcripts.
- [particle_podcast_search_transcripts](https://docs.particle.pro/mcp/tools/podcasts/podcast-search-transcripts.md): Semantic, keyword, or hybrid search over podcast transcripts — the single way to retrieve relevant dialogue, segments, and clips.
- [particle_podcast_list_episodes](https://docs.particle.pro/mcp/tools/podcasts/podcast-list-episodes.md): Filter-driven episode discovery across the catalog — by podcast, person, company, language, date range, duration, or transcript availability.
- [particle_podcast_get_episode_timeseries](https://docs.particle.pro/mcp/tools/podcasts/podcast-get-episode-timeseries.md): Time-bucketed episode counts — appearance, publication, and topic trend lines per day, week, or month.
- [particle_podcast_list_clips](https://docs.particle.pro/mcp/tools/podcasts/podcast-list-clips.md): Browse AI-extracted highlight clips ranked by engagement potential, or pull one clip's detail and transcript.
- [particle_podcast_list_related](https://docs.particle.pro/mcp/tools/podcasts/podcast-list-related.md): The shows most related to a podcast, best first — with a calibrated score, a band to branch on, and optionally the reasons behind each pairing.
- [particle_podcast_list_related_episodes](https://docs.particle.pro/mcp/tools/podcasts/podcast-list-related-episodes.md): Episodes from other shows that cover the same story or subject as an episode, best first — with a score, a band to branch on, and optionally the reasons.
## MCP server: Tools › People

- [particle_entity_resolve](https://docs.particle.pro/mcp/tools/people/entity-resolve.md): Resolve any named thing — person, company, place, or other entity — by free-text name in one union search.
- [particle_entity_get](https://docs.particle.pro/mcp/tools/people/entity-get.md): One knowledge-graph entity's profile — name, kind, description, and Wikipedia link.
- [particle_person_resolve](https://docs.particle.pro/mcp/tools/people/person-resolve.md): Resolve a person by free-text name to a canonical person slug.
- [particle_person_get](https://docs.particle.pro/mcp/tools/people/person-get.md): A person's profile — name, current role, bio, and optional external links, podcast appearances, and full role history.
## MCP server: Tools › Companies

- [particle_company_resolve](https://docs.particle.pro/mcp/tools/companies/company-resolve.md): Resolve a company by free-text name, ticker, SEC CIK, Wikidata QID, or domain.
- [particle_company_get](https://docs.particle.pro/mcp/tools/companies/company-get.md): Bundled profile for one company — identifiers, optional people, product hierarchy, and competitor list.
## MCP server: Tools › Alerts

- [particle_alert_create](https://docs.particle.pro/mcp/tools/alerts/alert-create.md): Create an alert that watches a single entity or keyword and emails you on podcast mentions or speaker appearances.
- [particle_alert_list](https://docs.particle.pro/mcp/tools/alerts/alert-list.md): List the alerts in your project, newest first.
- [particle_alert_get](https://docs.particle.pro/mcp/tools/alerts/alert-get.md): Fetch a single alert's full configuration, optionally with recent matches and deliveries.
- [particle_alert_update](https://docs.particle.pro/mcp/tools/alerts/alert-update.md): Update an existing alert — retitle, change cadence, pause/resume, or replace its watched entity or keyword.
- [particle_alert_delete](https://docs.particle.pro/mcp/tools/alerts/alert-delete.md): Delete an alert (soft delete; past matches and deliveries are retained).
- [particle_alert_preview](https://docs.particle.pro/mcp/tools/alerts/alert-preview.md): Preview how often an alert would fire before creating it.
- [particle_alert_list_matches](https://docs.particle.pro/mcp/tools/alerts/alert-list-matches.md): List the matches an alert has caught, newest first — with episode edges and optional transcript windows.
## MCP server: Tools › Topics

- [particle_topic_browse](https://docs.particle.pro/mcp/tools/topics/topic-browse.md): Navigate the topic taxonomy — without `parent_slug` returns top-level roots; with it returns direct children.
## MCP server: Tools › Podcast rankings

- [particle_podcast_get_rankings](https://docs.particle.pro/mcp/tools/podcast_rankings/podcast-get-rankings.md): Podcast chart rankings from Apple Podcasts and Spotify — current charts, biggest movers, and ranking history.
## MCP server: Tools › Podcast guests

- [particle_podcast_list_guests](https://docs.particle.pro/mcp/tools/podcast_guests/podcast-list-guests.md): Browse podcast guests across the catalog — the directory by lifetime appearances, or who's trending right now.
- [particle_podcast_get_guest](https://docs.particle.pro/mcp/tools/podcast_guests/podcast-get-guest.md): A guest's podcast-appearance profile — lifetime stats plus optional appearances, per-podcast rollup, and suitability exposure.
## MCP server: Tools › Podcast advertising

- [particle_company_get_podcast_ad_presence](https://docs.particle.pro/mcp/tools/podcast_advertising/company-get-podcast-ad-presence.md): Sponsor-side ad analytics for one company — totals, podcast/episode reach, host-read vs pre-recorded, and recent placements.
- [particle_podcast_get_sponsors](https://docs.particle.pro/mcp/tools/podcast_advertising/podcast-get-sponsors.md): Top sponsors for a single podcast plus aggregate ad stats — totals, unique sponsors, episodes with ads, host-read vs pre-recorded.
- [particle_podcast_get_sponsor_leaderboard](https://docs.particle.pro/mcp/tools/podcast_advertising/podcast-get-sponsor-leaderboard.md): Ranked list of the most-active sponsors across the podcast catalog, by ad count, podcast reach, or episode reach.
- [particle_podcast_get_episode_ads](https://docs.particle.pro/mcp/tools/podcast_advertising/podcast-get-episode-ads.md): Every detected ad read inside one episode — sponsor, product, offer, read type, placement, and exact offsets.
- [particle_podcast_get_ad_trends](https://docs.particle.pro/mcp/tools/podcast_advertising/podcast-get-ad-trends.md): Podcast advertising momentum — sponsors ramping up or pulling back, and one company's ad volume over time.
## MCP server: Tools › Podcast publishers

- [particle_podcast_get_publisher](https://docs.particle.pro/mcp/tools/podcast_publishers/podcast-get-publisher.md): A podcast publisher's profile — name, slug, catalog size, and optional shows, bias profile, and suitability profile.
## MCP server: Tools › Podcast ratings

- [particle_podcast_get_ratings](https://docs.particle.pro/mcp/tools/podcast_ratings/podcast-get-ratings.md): Listener-review ratings for one podcast — aggregate summary, per-platform breakdown, sentiment, and recent reviews.
## MCP server: Tools › Podcast bias

- [particle_podcast_get_bias_leaderboard](https://docs.particle.pro/mcp/tools/podcast_bias/podcast-get-bias-leaderboard.md): Rank podcast publishers by political-bias metrics across their analyzed catalogs.
- [particle_podcast_list_bias_publishers](https://docs.particle.pro/mcp/tools/podcast_bias/podcast-list-bias-publishers.md): Which publishers have the most podcasts in one political-bias bucket — by raw count or by share of catalog.
## MCP server: Tools › Podcast suitability

- [particle_podcast_get_suitability_leaderboard](https://docs.particle.pro/mcp/tools/podcast_suitability/podcast-get-suitability-leaderboard.md): Rank podcast publishers by IAB/GARM brand-suitability composition across their analyzed catalogs.
- [particle_podcast_list_suitability_category_publishers](https://docs.particle.pro/mcp/tools/podcast_suitability/podcast-list-suitability-category-publishers.md): Which publishers' catalogs are most (or least) exposed to one IAB/GARM brand-safety category.
## Optional

- [Full documentation corpus](https://docs.particle.pro/llms-full.txt): Every documentation page inlined as one markdown file
- [Endpoint and tool map](https://api.particle.pro/llms.txt): Every public REST endpoint and MCP tool with its documentation page and keyless price
- [Agent setup playbook](https://api.particle.pro/agents.md): Connect a client over MCP, the REST API, or x402 and run a first query
- [Agent authentication (auth.md)](https://api.particle.pro/auth.md): The credential recipe: discovery, the decision tree, registration, revocation
- [OpenAPI specification](https://api.particle.pro/openapi.json): Machine-readable REST schema with payment terms
- [x402 manifest](https://api.particle.pro/.well-known/x402): Payable endpoints and payment terms
- [Status](https://status.particle.pro): Service status