Get a podcast's latest brand suitability assessment

Returns the most recent brand suitability assessment for a podcast against the IAB Tech Lab Content Taxonomy 3.x Brand Safety & Suitability Framework (the industry-standard 12-category taxonomy formerly stewarded by GARM): overall tier, per-category prevalence and treatment, evidence excerpts from sampled episodes, and the methodology that produced the rating. Pass include=trend for a deterministically-derived comparison against the prior assessment, or include=history for the list of prior assessments. Returns 404 when the podcast is not found or has not yet been analyzed.

GET /v1/podcasts/{id}/suitability

cURL

cURL

curl -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/podcasts/{id}/suitability"

200

{
  "categories": [
    {
      "code": "<string>",
      "description": "<string>",
      "prevalence": "<string>",
      "reasoning": "<string>",
      "risk_level": "<string>",
      "treatment": "<string>",
      "evidence": [
        {
          "episode_id": "<string>",
          "episode_title": "<string>",
          "excerpt": "<string>",
          "episode_slug": "<string>"
        }
      ],
      "verdict_basis": "<string>"
    }
  ],
  "confidence": "<string>",
  "evaluated_at": "2023-11-07T05:31:56Z",
  "methodology": "<string>",
  "overall_tier": "<string>",
  "sample_window_end_at": "2023-11-07T05:31:56Z",
  "sample_window_start_at": "2023-11-07T05:31:56Z",
  "summary": "<string>",
  "episodes_analyzed": 123,
  "history": [
    {
      "confidence": "<string>",
      "episodes_analyzed": 123,
      "evaluated_at": "2023-11-07T05:31:56Z",
      "overall_tier": "<string>",
      "sample_window_end_at": "2023-11-07T05:31:56Z",
      "sample_window_start_at": "2023-11-07T05:31:56Z"
    }
  ],
  "sample_episode_ids": [
    "<string>"
  ],
  "trend": {
    "direction": "<string>",
    "changed_categories": [
      {
        "code": "<string>",
        "new_prevalence": "<string>",
        "new_risk_level": "<string>",
        "new_treatment": "<string>",
        "prior_prevalence": "<string>",
        "prior_risk_level": "<string>",
        "prior_treatment": "<string>"
      }
    ],
    "prior_evaluated_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Path Parameters

id · string · required

Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID

Query Parameters

include · enum<string>[] | null

Optional response sections. Pass include=trend for a deterministically-derived comparison against the prior assessment, include=history for the list of prior assessments, or include=trend,history for both.

Available options: trend, history

Response

200

application/json

OK

categories · object[] | null · required

Per-category breakdown across all 12 brand-safety categories. Always 12 entries even when prevalence is NONE — the assessment records that every category was actively considered.

Show child attributes

confidence · string · required

Agent confidence in the verdict: LOW, MEDIUM, or HIGH.

evaluated_at · string<date-time> · required

When the assessment was performed.

methodology · string · required

Note on what the agent sampled (segments + transcripts read, sponsor cross-checks).

overall_tier · string · required

Suitability verdict: SAFE (Low Risk), LIMITED (Medium), SENSITIVE (High), or UNSAFE (Brand Safety Floor).

sample_window_end_at · string<date-time> · required

Published-at of the newest episode in the assessment window.

sample_window_start_at · string<date-time> · required

Published-at of the oldest episode in the assessment window.

summary · string · required

Customer-facing 2-4 sentence explanation of the verdict.

episodes_analyzed · integer<int64>

Number of episodes that informed the assessment.

history · object[] | null

Prior assessments ordered most-recent first. Present when include=history.

Show child attributes

sample_episode_ids · string[] | null

Episode IDs in the contiguous window the agent analyzed.

trend · object

Deterministic comparison against the prior assessment. Present when include=trend; INSUFFICIENT_HISTORY before a second assessment exists.

Show child attributes