# Podseeker API

> Programmatic podcast search, profile data, verified contacts, and contact enrichment for AI agents, applications, scripts, and automations.

Podseeker provides programmatic access to a curated database of active, contactable podcasts with contact emails, booking difficulty, host information, and audience data. Dormant and low-quality shows are filtered so automated workflows can focus on podcasts worth evaluating.

## Start Here

- [Get an API key](https://app.podseeker.co/auth/registration?product=api)
- [API documentation](https://app.podseeker.co/api/docs)
- [Postman collection](https://www.postman.com/podseeker-3052715/podseeker-public-api/overview)
- [Open the API product](https://app.podseeker.co/api)
- [API pricing](https://www.podseeker.co/podcast-api)
- [Database product](https://app.podseeker.co/database.md)

## Base URL

`https://app.podseeker.co/api/v1`

## Authentication

All requests require an API key as a Bearer token:

```http
Authorization: Bearer ps_your_api_key_here
```

Create and manage keys in the API product at https://app.podseeker.co/api.

## Endpoints

### Search Podcasts

`GET /api/v1/podcasts/search`

Find podcasts matching a query and optional filters. The endpoint returns 50 results per page and supports up to 5,000 results.

Parameters:

- `query` (string): Search term such as `health`, `entrepreneurship`, or `AI`.
- `active` (boolean): `true`, `yes`, or `1` to require an active podcast.
- `has_guest` (boolean): `true`, `yes`, or `1` to require a show that accepts guests.
- `has_email` (boolean): `true`, `yes`, or `1` to require a known contact email.
- `topic` (string, repeatable): Filter by topic, such as `topic=leadership&topic=coaching`.
- `location` (string, repeatable): `usa`, `uk`, `au`, `ca`, `ie`, `sg`, `nz`, or `za`.
- `listener` (string, repeatable): `<100`, `100-1k`, `1k-10k`, `10k-100k`, `100k-1m`, or `>1m`.
- `booking_difficulty` (string, repeatable): `very_low`, `low`, `medium`, `high`, `very_high`, or `not_applicable`.
- `gender_skew` (string): `male`, `female`, or `neutral`.
- `sort` (string): `listeners_desc`, `listeners_asc`, `latest_episode_desc`, `latest_episode_asc`, `youtube_subscribers_desc`, or `instagram_followers_desc`.
- `page` (integer): Page number from 0 through 99.

Invalid enumerated values and malformed booleans return HTTP 422 without consuming a credit. The response includes a `details` array containing `param`, `given`, and `allowed` values.

Example:

```bash
curl -H "Authorization: Bearer ps_your_key" \
  "https://app.podseeker.co/api/v1/podcasts/search?query=entrepreneurship&active=true&has_guest=true&has_email=true"
```

Search results include:

- `id`, `title`, `publisher`, and `description`
- `topics`
- `location`
- `estimated_listeners`, a rounded per-episode estimate rather than an exact audited count
- `episode_count` and `episode_frequency`
- `latest_episode_date` and `rating`
- `has_guests` and `has_email`
- `booking_difficulty`
- `gender_skew`

### Get Podcast Details

`GET /api/v1/podcasts/:id`

Get a complete podcast record with available contacts, hosts, pitching context, and social data.

```bash
curl -H "Authorization: Bearer ps_your_key" \
  "https://app.podseeker.co/api/v1/podcasts/625373"
```

The response includes the search fields plus:

- `contacts.primary_email`
- `contacts.all_emails`
- `contacts.has_contact_form`
- `contacts.enriched_contacts`
- `website_url` and `rss_url`
- `pitching_description`
- `hosts`, including available name, role, and professional biography
- `guest_caliber`, including prominence, booking difficulty, typical credentials, and achievements
- `recent_guests`
- `social.youtube_subscribers` and `social.instagram_followers`

### Enrich Podcast Contacts

`POST /api/v1/podcasts/:id/enrich`

Start contact enrichment for a podcast. Enrichment looks for direct hosts, producers, bookers, and other useful contacts. It costs 10 credits and usually takes 60-120 seconds.

Check `GET /podcasts/:id` first. If `enriched_contacts` already contains useful people, another enrichment may not be necessary. Each accepted enrichment request initially consumes 10 credits.

If enrichment fails or finds no direct contacts, all 10 credits are automatically refunded. A successful enrichment has a 30-day cooldown; requesting it again during that period returns HTTP 429.

```bash
curl -X POST \
  -H "Authorization: Bearer ps_your_key" \
  "https://app.podseeker.co/api/v1/podcasts/625373/enrich"
```

The response includes:

- `enrichment_id`, formatted like `enr_123`
- `status`, initially `enriching`
- `estimated_seconds`

### Check Enrichment Status

`GET /api/v1/enrichments/:enrichment_id`

Poll an enrichment without consuming a credit.

```bash
curl -H "Authorization: Bearer ps_your_key" \
  "https://app.podseeker.co/api/v1/enrichments/enr_123"
```

The response includes:

- `status`: `processing`, `completed`, or `failed`
- `podcast_id`
- `note`, when applicable, explaining that no contacts were found or the run failed and credits were refunded

After a completed enrichment, request `GET /podcasts/:id` again to retrieve `enriched_contacts.people`.

### Check Usage

`GET /api/v1/usage`

Read the authoritative committed credit balance. This endpoint is free and is preferable to treating a prior response header as the current balance.

```bash
curl -H "Authorization: Bearer ps_your_key" \
  "https://app.podseeker.co/api/v1/usage"
```

The response includes:

- `credits_used`
- `credits_included`
- `credits_remaining`
- `overage_credits`
- `overage_charge`
- `plan`
- `status`: `active` or `trialing`
- `period_end`, or `null` during the fixed-credit trial

## Enrichment State

The `enriched_contacts` field on a podcast explains its state:

- `null`: The podcast has not been enriched.
- `{ "status": "enriching" }`: Enrichment is running. Poll the enrichment endpoint every 15-30 seconds.
- `{ "last_updated_at": "...", "people": [...] }`: Enrichment completed and its contacts are available.

## Pricing and Credits

The API costs $99 per month and includes 2,000 credits. Overage is billed at $0.05 per credit.

- Search request: 1 credit.
- Podcast-detail request: 1 credit.
- Contact enrichment: 10 credits, automatically refunded if it fails or finds no direct contacts.
- Enrichment-status request: free.
- Usage request: free.

New API customers receive 100 free credits to try. The API uses a credit trial rather than the Database product's time-based trial.

See [pricing.md](https://app.podseeker.co/pricing.md) for the shared pricing reference.

## Usage Headers

Billable responses include:

- `X-Credits-Used`
- `X-Credits-Included`
- `X-Credits-Remaining`
- `X-Overage-Credits`
- `X-Overage-Charge`

Use `GET /api/v1/usage` when an on-demand, strongly consistent balance is required.

## Rate Limit

The API allows 60 requests per minute. An exceeded limit returns HTTP 429 with a `Retry-After` header.

## Errors

- `401`: API key is missing or invalid.
- `402`: Credits are exhausted, or the API subscription is inactive.
- `403`: API key is inactive or revoked.
- `404`: Podcast or enrichment was not found.
- `422`: A search parameter is invalid. Correct the value using the response's `details`; no credit is charged.
- `429`: Rate limit or enrichment cooldown. Follow the response instructions before retrying.

## Efficient Agent Workflow

1. Search for qualified podcasts with a focused query and filters.
2. Present the search fields to the user before spending credits on detail requests.
3. Fetch full details only for podcasts the user wants to investigate.
4. Use known contacts and host context to prepare outreach.
5. Trigger enrichment only when the existing podcast details do not contain sufficient direct contacts.
6. Poll enrichment status for free, then fetch the updated podcast record.

## API and Database Are Separate Products

The API provides programmatic podcast data. [Podseeker Database](https://app.podseeker.co/database.md) is the self-serve application for PR teams to research podcasts, collaborate, draft pitches, send through Gmail or Outlook, and manage replies and campaigns.

An organization may subscribe to either product or both. API credits do not provide Database seats or pitch allowances, and Database quotas do not provide API credits.

## Support

- Documentation: https://app.podseeker.co/api/docs
- Postman collection: https://www.postman.com/podseeker-3052715/podseeker-public-api/overview
- API pricing: https://www.podseeker.co/podcast-api
- Email: support@podseeker.co