podchaser

Troubleshooting

If requests fail, run zero doctor check-connector --env-name PODCHASER_TOKEN or zero doctor check-connector --url https://api.podchaser.com/graphql --method POST

How to Use

1. Search Podcasts

Search for podcasts by keyword:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(searchTerm: \"technology\", first: 5) { paginatorInfo { count } data { id title description author { name } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

3. Get Podcast Details

Get detailed information about a specific podcast by ID:

Note: The type field is required in the identifier. Use PODCHASER for Podchaser IDs, APPLE_PODCASTS for Apple IDs, or SPOTIFY for Spotify IDs.

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { id title description url imageUrl language ratingAverage ratingCount author { name } categories { title } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

4. Search Episodes

Search for episodes across all podcasts:

Write to /tmp/podchaser_request.json:

{
  "query": "{ episodes(searchTerm: \"AI\", first: 5) { paginatorInfo { count } data { id title description airDate length podcast { title } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

5. Get Podcast Episodes

Get episodes for a specific podcast:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { id title episodes(first: 10) { data { id title description airDate length } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

6. Get Episode Details

Get detailed information about a specific episode:

Write to /tmp/podchaser_request.json:

{
  "query": "{ episode(identifier: { id: \"789012\", type: PODCHASER }) { id title description airDate length url imageUrl podcast { id title } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

7. Get Podcast Categories

Categories are available as a field on podcast objects. Get categories for a specific podcast:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcast(identifier: { id: \"717178\", type: PODCHASER }) { title categories { title slug } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

8. Filter Podcasts by Category

Get podcasts in a specific category:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(filters: { categories: [\"technology\"] }, first: 10) { data { id title description ratingAverage } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

9. Get Chart Rankings

Get Apple Podcasts chart data:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(filters: { hasAppleChartRank: true }, sort: { sortBy: APPLE_CHART_RANK, direction: ASC }, first: 10) { data { id title appleChartRank } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

10. Get Creator/Host Information

Search for podcast creators:

Write to /tmp/podchaser_request.json:

{
  "query": "{ creators(searchTerm: \"Joe Rogan\", first: 5) { data { pcid name bio credits { data { podcast { title } } } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

11. Preview Query Cost

Check how many points a query will cost before executing:

Write to /tmp/podchaser_request.json:

{
  "query": "{ podcasts(searchTerm: \"tech\", first: 10) { data { id title description episodes(first: 5) { data { id title } } } } }"
}

Then run:

curl -s -X POST "https://api.podchaser.com/graphql/cost" --header "Content-Type: application/json" --header "Authorization: Bearer $PODCHASER_TOKEN" -d @/tmp/podchaser_request.json

GraphQL Schema Reference

Main Queries

Query	Description
`podcast(identifier: {id: "...", type: PODCHASER})`	Get single podcast by ID
`podcasts(searchTerm: "...", first: N)`	Search podcasts
`episode(identifier: {id: "...", type: PODCHASER})`	Get single episode by ID
`episodes(searchTerm: "...", first: N)`	Search episodes
`creators(searchTerm: "...", first: N)`	Search creators/hosts
`networks(searchTerm: "...", first: N)`	Search podcast networks
`chartCategories(platform: APPLE_PODCASTS)`	List chart categories (requires paid plan)

Identifier Types

The type field is required when using identifier to fetch a podcast or episode:

Type	Description
`PODCHASER`	Podchaser internal ID
`APPLE_PODCASTS`	Apple Podcasts ID
`SPOTIFY`	Spotify ID

Podcast Fields

Field	Type	Description
`id`	ID	Unique identifier
`title`	String	Podcast title
`description`	String	Podcast description
`url`	String	Podcast website URL
`imageUrl`	String	Cover art URL
`language`	String	Primary language
`ratingAverage`	Float	Average user rating
`ratingCount`	Int	Number of ratings
`author`	Creator	Podcast author/creator
`categories`	[Category]	Associated categories
`episodes(first: N)`	EpisodeList	Podcast episodes (paginated)

Episode Fields

Field	Type	Description
`id`	ID	Unique identifier
`title`	String	Episode title
`description`	String	Episode description
`airDate`	Date	Publication date
`length`	Int	Duration in seconds
`url`	String	Episode URL
`imageUrl`	String	Episode artwork URL
`podcast`	Podcast	Parent podcast

Creator Fields

Field	Type	Description
`pcid`	String	Unique identifier
`name`	String	Creator name
`bio`	String	Biography
`imageUrl`	String	Profile image URL
`credits`	CreditList	Podcast appearances

Filter Options

Filter	Values
`categories`	Category slugs
`language`	ISO language codes
`hasAppleChartRank`	Boolean
`hasSpotifyChartRank`	Boolean

Sort Options

sortBy	Description
`RELEVANCE`	Search relevance
`POPULARITY`	Overall popularity
`RATING`	User rating
`APPLE_CHART_RANK`	Apple ranking
`SPOTIFY_CHART_RANK`	Spotify ranking
`LATEST_EPISODE`	Most recent episode

Rate Limits

Request Limit: 50 requests per 10 seconds
Points System: Query cost based on fields returned
Response Headers:
- X-Podchaser-Points-Remaining: Available points
- X-Podchaser-Query-Cost: Points consumed

Example costs:

Basic podcast metadata: ~9 points
Search 10 podcasts with details: ~100 points

Guidelines

Store Access Token: Tokens last 1 year, avoid requesting new tokens for each query
Preview Costs: Use /graphql/cost endpoint to estimate query cost before execution
Use Limited Scope: For client-side apps, request tokens with limited_scope: true (1 hour expiry)
Optimize Queries: Request only needed fields to minimize points consumption
Handle Rate Limits: Check Retry-After header on 429 responses
Security: Never expose regular access tokens in client-side code

About this skill

Troubleshooting

How to Use

1. Search Podcasts

3. Get Podcast Details

4. Search Episodes

5. Get Podcast Episodes

6. Get Episode Details

7. Get Podcast Categories

8. Filter Podcasts by Category

9. Get Chart Rankings

10. Get Creator/Host Information

11. Preview Query Cost

GraphQL Schema Reference

Main Queries

Identifier Types

Podcast Fields

Episode Fields

Creator Fields

Filter Options

Sort Options

Rate Limits

Guidelines