FreeTranscriptAPI

https://freetranscriptapi.com/docs
Admin
FreeTranscriptAPI is a REST API and MCP service that fetches structured YouTube video transcripts...
Tokens:5,238
Snippets:38
Trust Score:2.9
Update:1 day ago
Show doc for...
Tokens:
Raw
### Python: Fetch transcript with requests library

Source: https://freetranscriptapi.com/docs

Use the requests library to GET a transcript and print the transcript text. No API key required for the quick start. Rate limit: 20 requests per hour per IP without a key.

```python
import requests

response = requests.get(
    "https://api.freetranscriptapi.com/v1/transcript",
    params={"video_url": "dQw4w9WgXcQ"},
)

data = response.json()
print(data["transcript"])
```

--------------------------------

### JSON response example

Source: https://freetranscriptapi.com/docs

Shows the structure of a successful transcript response, including language, title, and an array of transcript segments with text, start time, and duration.

```json
{
  "language": "en",
  "title": "Example Video Title",
  "transcript": [
    {
      "text": "Hello world.",
      "start": 0.0,
      "duration": 2.1
    }
  ]
}
```

--------------------------------

### cURL: Fetch transcript with video URL

Source: https://freetranscriptapi.com/docs

Send a GET request to the transcript endpoint with a video URL or ID. No API key required for the quick start. Rate limit: 20 requests per hour per IP without a key.

```bash
curl "https://api.freetranscriptapi.com/v1/transcript?video_url=dQw4w9WgXcQ"
```

--------------------------------

### List languages JSON response

Source: https://freetranscriptapi.com/docs

Example response from the /languages endpoint, showing language codes, names, and whether they are auto-generated.

```json
{
  "languages": [
    {
      "code": "en",
      "name": "English",
      "auto_generated": false
    },
    {
      "code": "es",
      "name": "Spanish",
      "auto_generated": true
    }
  ]
}
```

--------------------------------

### JavaScript: Fetch transcript with fetch API

Source: https://freetranscriptapi.com/docs

Use the fetch API to request a transcript and log the transcript text. No API key required for the quick start. Rate limit: 20 requests per hour per IP without a key.

```javascript
const response = await fetch(
  "https://api.freetranscriptapi.com/v1/transcript?video_url=dQw4w9WgXcQ"
);

const data = await response.json();
console.log(data.transcript);
```

--------------------------------

### GET /transcript

Source: https://freetranscriptapi.com/docs

Returns the full transcript for a YouTube video. Accepts a video URL or 11-character video ID.

```APIDOC
## GET /transcript

### Description
Returns the full transcript for a YouTube video. Accepts a video URL or 11-character video ID.

### Method
GET

### Endpoint
https://api.freetranscriptapi.com/v1/transcript

### Parameters
#### Query Parameters
- **video_url** (string) - Required - YouTube video URL or video ID (e.g. dQw4w9WgXcQ).
- **lang** (string) - Optional - Preferred language code (e.g. en, es, fr). Defaults to en. Falls back to available captions if not found.
- **format** (string) - Optional - Response format. Defaults to json. Set to text for plain text output.

### Request Example
```
curl "https://api.freetranscriptapi.com/v1/transcript?video_url=dQw4w9WgXcQ"
```

### Response
#### Success Response (200)
- **language** (string) - Language code of the transcript.
- **title** (string) - Title of the video.
- **transcript** (array) - Array of transcript segments.
  - **text** (string) - Text of the segment.
  - **start** (number) - Start time of the segment in seconds.
  - **duration** (number) - Duration of the segment in seconds.

#### Response Example
```
{
  "language": "en",
  "title": "Example Video Title",
  "transcript": [
    {
      "text": "Hello world.",
      "start": 0.0,
      "duration": 2.1
    }
  ]
}
```

### Authentication
API keys are optional. Without one, you can make up to 20 requests per hour per IP address. Include an API key in the `Authorization` header to use your account credits. Signup includes 1,000 free credits.

`Authorization: Bearer fta_live_sk_...`

cURL example with authentication:
```
curl -H "Authorization: Bearer fta_live_sk_..." \
  "https://api.freetranscriptapi.com/v1/transcript?video_url=dQw4w9WgXcQ"
```
```

--------------------------------

### GET /languages

Source: https://freetranscriptapi.com/docs

Returns all available caption languages for a video before fetching the transcript. Requires a video URL or ID as a query parameter.

```APIDOC
## GET /languages

### Description
Returns all available caption languages for a video before fetching the transcript.

### Method
GET

### Endpoint
/languages

### Parameters
#### Query Parameters
- **video_url** (string) - Required - YouTube video URL or video ID.

### Request Example
```
curl "https://api.freetranscriptapi.com/v1/languages?video_url=dQw4w9WgXcQ"
```

### Response
#### Success Response (200)
- **languages** (array) - List of available languages.
  - **code** (string) - Language code (e.g., "en").
  - **name** (string) - Language name (e.g., "English").
  - **auto_generated** (boolean) - Whether the captions are auto-generated.

#### Response Example
```
{
  "languages": [
    {
      "code": "en",
      "name": "English",
      "auto_generated": false
    },
    {
      "code": "es",
      "name": "Spanish",
      "auto_generated": true
    }
  ]
}
```
```

--------------------------------

### Health check JSON response

Source: https://freetranscriptapi.com/docs

Example response from the /health endpoint, showing status and version.

```json
{
  "status": "ok",
  "version": "1.0.0"
}
```

--------------------------------

### GET /health

Source: https://freetranscriptapi.com/docs

Returns the API status. No authentication required. Use this endpoint for uptime monitoring.

```APIDOC
## GET /health

### Description
Returns the API status. No authentication required. Use this endpoint for uptime monitoring.

### Method
GET

### Endpoint
/health

### Request Example
```
curl "https://api.freetranscriptapi.com/v1/health"
```

### Response
#### Success Response (200)
- **status** (string) - API status (e.g., "ok").
- **version** (string) - API version (e.g., "1.0.0").

#### Response Example
```
{
  "status": "ok",
  "version": "1.0.0"
}
```
```

--------------------------------

### Transcript Response Format

Source: https://freetranscriptapi.com/docs

Describes the JSON structure of a successful transcript response, including language, title, and an array of caption lines with text, start time, and duration.

```APIDOC
## Transcript Response Format

### Description
Transcript responses include the detected language, video title, and an array of caption lines.

### Response Fields
- **language** (string) - Required - ISO language code of the returned transcript.
- **title** (string) - Required - Title of the YouTube video.
- **transcript** (array) - Required - Array of caption line objects.
- **transcript[].text** (string) - Required - Caption text for this line.
- **transcript[].start** (number) - Required - Start time in seconds.
- **transcript[].duration** (number) - Required - Duration of this caption line in seconds.

### Response Example
{
  "language": "en",
  "title": "Example Video",
  "transcript": [
    {
      "text": "Hello world",
      "start": 0.0,
      "duration": 2.5
    }
  ]
}
```

--------------------------------

### GET /v1/transcript

Source: https://freetranscriptapi.com/docs

Fetches the transcript for a given YouTube video. Pass the video URL or video ID as the video_url query parameter. Returns structured JSON data containing the transcript.

```APIDOC
## GET /v1/transcript

### Description
Fetches the transcript for a given YouTube video. Pass the video URL or video ID as the video_url query parameter. Returns structured JSON data containing the transcript.

### Method
GET

### Endpoint
https://api.freetranscriptapi.com/v1/transcript

### Parameters
#### Query Parameters
- **video_url** (string) - Required - The YouTube video URL or video ID.

### Request Example
```
curl "https://api.freetranscriptapi.com/v1/transcript?video_url=dQw4w9WgXcQ"
```

### Response
#### Success Response (200)
- **transcript** (string) - The transcript text.

#### Response Example
```json
{
  "transcript": "..."
}
```
```

--------------------------------

### MCP Endpoint - https://api.freetranscriptapi.com/mcp

Source: https://freetranscriptapi.com/docs

Hosted MCP endpoint for AI assistants to fetch YouTube transcripts as tools. Connect from Cursor, ChatGPT, Claude, Windsurf, or any client that supports remote MCP servers over HTTPS. Pass your API key in the Authorization header as Bearer fta_live_sk_...

```APIDOC
## MCP Endpoint

### Description
Hosted MCP endpoint for AI assistants to fetch YouTube transcripts as tools. Connect from Cursor, ChatGPT, Claude, Windsurf, or any client that supports remote MCP servers over HTTPS. No local package or npx install required.

### Endpoint
https://api.freetranscriptapi.com/mcp

### Authentication
Pass your API key in the Authorization header as `Bearer fta_live_sk_...`. Create a key in your dashboard. The same rate limits apply as the REST API.

### Tools Exposed
- **get_youtube_transcript** (tool) - Fetch a transcript by video URL or ID. Optional lang and format (json or text).
- **list_youtube_languages** (tool) - List available caption languages for a video before fetching.

### Configuration Examples

#### Cursor, Claude Desktop, and Windsurf
Add a remote MCP server in your client config. Replace the API key with yours:

```json
{
  "mcpServers": {
    "freetranscriptapi": {
      "url": "https://api.freetranscriptapi.com/mcp",
      "headers": {
        "Authorization": "Bearer fta_live_sk_..."
      }
    }
  }
}
```

In Cursor: Settings → MCP → Edit config. In Claude Desktop: edit your `claude_desktop_config.json`. Other editors with MCP support follow the same URL plus headers pattern.

#### ChatGPT
ChatGPT connects to remote MCP servers over HTTPS (not local stdio). You need a paid plan and Developer Mode enabled.

1. Open Settings → Apps & Connectors (or Connectors). Enable Developer Mode if prompted.
2. Click Create (or New connector) and choose a custom MCP connector.
3. Set the connector URL to `https://api.freetranscriptapi.com/mcp`.
4. Set authentication to Token (or API key) and paste your API key, or use a Bearer token in the format `fta_live_sk_...`.
5. Save the connector, then mention it in a chat (for example with @freetranscriptapi) when you want transcript tools available.

### Rate Limits
Without an API key, unauthenticated MCP requests follow the same 20 requests per hour per IP limit as the REST API. With an API key, transcript requests use account credits.
```

--------------------------------

### Remote MCP server configuration

Source: https://freetranscriptapi.com/docs

Configuration for adding the FreeTranscriptAPI MCP server to clients like Cursor, Claude Desktop, and Windsurf. Replace the API key with your own.

```json
{
  "mcpServers": {
    "freetranscriptapi": {
      "url": "https://api.freetranscriptapi.com/mcp",
      "headers": {
        "Authorization": "Bearer fta_live_sk_..."
      }
    }
  }
}
```

--------------------------------

### cURL request with Authorization header

Source: https://freetranscriptapi.com/docs

Sends a request to the transcript endpoint with an API key in the Authorization header. The key is optional; without it, rate limits apply (20 requests per hour per IP).

```bash
curl -H "Authorization: Bearer fta_live_sk_..." \
  "https://api.freetranscriptapi.com/v1/transcript?video_url=dQw4w9WgXcQ"
```

--------------------------------

### List languages cURL request

Source: https://freetranscriptapi.com/docs

Fetches available caption languages for a YouTube video. Requires the video_url parameter (URL or ID).

```bash
curl "https://api.freetranscriptapi.com/v1/languages?video_url=dQw4w9WgXcQ"
```

--------------------------------

### cURL request for plain text transcript

Source: https://freetranscriptapi.com/docs

Fetches a transcript in plain text format by adding the format=text parameter.

```bash
curl "https://api.freetranscriptapi.com/v1/transcript?video_url=dQw4w9WgXcQ&format=text"
```

--------------------------------

### Error Codes

Source: https://freetranscriptapi.com/docs

Lists the error codes returned by the API, including HTTP status, machine-readable code, and description.

```APIDOC
## Error Codes

### Description
Errors return a JSON object with an `error` field containing a machine-readable code and human-readable message.

### Error Response Format
{
  "error": {
    "code": "video_not_found",
    "message": "No transcript available for this video."
  }
}

### Error Codes Table
| Status | Code | Description |
| --- | --- | --- |
| 400 | invalid_request | Missing or invalid query parameters. |
| 401 | unauthorized | Missing, invalid, or revoked API key. |
| 404 | video_not_found | Video does not exist or has no captions. Authenticated requests still use 1 credit. |
| 402 | insufficient_credits | Account credit balance is empty. |
| 429 | rate_limit_exceeded | Anonymous hourly request limit reached for this IP address. |
| 429 | anonymous_daily_cap_exceeded | Platform-wide anonymous free tier exhausted for the UTC day. The message includes how long until the daily counter resets. |
| 500 | internal_error | Unexpected server error. Retry the request. |
```

--------------------------------

### Health check cURL request

Source: https://freetranscriptapi.com/docs

Checks the API status. No authentication required; use for uptime monitoring.

```bash
curl "https://api.freetranscriptapi.com/v1/health"
```
Tokens:
Raw