API documentation

Authentication, endpoints, credit rates, and client setup.

Your first request

curl 'https://api.fetchfox.net/youtube/transcript' \
  --get --data-urlencode 'url=VIDEO_URL' \
  -H 'x-access-key: YOUR_KEY'

Base URL: https://api.fetchfox.net

Try it in the playground

Authentication

Send your project key in the x-access-key header. Keep it on your server. GET requests use query parameters; POST requests use JSON with the same input names.

One project key works across REST and MCP. Rotating it immediately invalidates the previous key.

Credits & errors

Read /credits for your balance. The x-credits-used response header reports each request’s charge. Validation errors and failed processing do not incur a success charge. Successful cache hits can be free.

API credit rates
Operation	Credits
YouTube transcript	1 per video
Instagram profile or post stats	1 per request
Instagram posts or reels	1 per 20 returned items
TikTok post stats or channel videos	1 per request
TikTok search	1 per 50 returned results

Errors include an HTTP status, an error code, and retryability where applicable. Use bounded retries for transient errors and respect Retry-After; do not retry missing or private content indefinitely.

Limits, latency, and freshness

Responses report your rate window in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Free accounts allow 20 request attempts per calendar month (UTC), separate from the 10 free credits. Paid monthly plans are exempt from this account cap. Cached responses and failed or invalid authenticated operation attempts count toward it. Concurrency and daily attempt caps also apply; failed upstream attempts count toward these caps even though they use no credits. HTTP 429 includes Retry-After. Back off before retrying and limit retries.

Requests may take several seconds or longer depending on platform access, retries and caching. There is no published latency or uptime SLA. Your request history records each request’s duration; the status page shows the latest reported operation state.

Source data is a snapshot at extraction time. Free-tier YouTube transcript results can be cached for five minutes; source captions and public counts may change independently. Store your own retrieval time when building a dataset or comparing historical values. A successful response does not guarantee every optional field exists.

Only use content you are permitted to access and process. FetchFox does not grant rights to platform content or guarantee that a use complies with platform terms. Review our Terms and the source platform’s rules.

Give your agent access to public social data

Ask it to read a video transcript, compare creator profiles, or find TikTok videos. FetchFox exposes the same operations as MCP tools, using the same project key and credits as REST.

Cursor

Add this to your personal ~/.cursor/mcp.json. Replace YOUR_KEY with your project key and enable FetchFox in MCP settings.

{
  "mcpServers": {
    "fetchfox": {
      "url": "https://mcp.fetchfox.net/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Claude Code

Run this in your terminal, replace YOUR_KEY, then use /mcp to check the connection.

claude mcp add --transport http fetchfox 'https://mcp.fetchfox.net/mcp' \
  --header 'Authorization: Bearer YOUR_KEY'

You need a FetchFox project key first. Keep it in personal configuration, outside shared repositories. These instructions are for Cursor and Claude Code; Claude web and Desktop connector setup differs.

MCP tools and authentication

Connect with MCP

Connect a Streamable HTTP MCP client to the endpoint below and send Authorization: Bearer YOUR_KEY. Calls share your REST credit balance.

https://mcp.fetchfox.net/mcp

Discovery exposes 8 tools. Expand a platform to see the available tools.

YouTube1 tools

youtube_transcript

TikTok3 tools

tiktok_stats
tiktok_search
tiktok_channel_videos

Instagram4 tools

instagram_stats
instagram_channel_stats
instagram_channel_posts
instagram_channel_reels

Use your project API key to connect; OAuth is not enabled for this deployment.

Endpoint reference

Find an operation, then expand it for input details.

10 endpoints

GET/credits

Get the authenticated project’s remaining monthly and purchased credits. This request does not consume credits.

{}

GET / POST/instagram/channel-posts

Get recent posts from an Instagram profile's feed.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL of the resource"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return"
    },
    "access_key": {
      "type": "string",
      "description": "Project access key (also accepted as x-access-key header)"
    }
  },
  "nullable": true,
  "required": [
    "url"
  ]
}

GET / POST/instagram/channel-reels

Get recent reels from an Instagram profile's reels tab.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL of the resource"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return"
    },
    "access_key": {
      "type": "string",
      "description": "Project access key (also accepted as x-access-key header)"
    }
  },
  "nullable": true,
  "required": [
    "url"
  ]
}

GET / POST/instagram/channel-stats

Get stats and metadata for an Instagram profile.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL of the resource"
    },
    "access_key": {
      "type": "string",
      "description": "Project access key (also accepted as x-access-key header)"
    }
  },
  "nullable": true,
  "required": [
    "url"
  ]
}

GET / POST/instagram/stats

Get engagement metrics and metadata for an Instagram post or reel. Views are optional by default: returns media immediately with null for unavailable views. Set requireViews=true to require a verified count; unavailable strict requests return 503 without a charge.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL of the resource"
    },
    "access_key": {
      "type": "string",
      "description": "Project access key (also accepted as x-access-key header)"
    },
    "requireViews": {
      "enum": [
        true,
        false,
        "true",
        "false",
        "1",
        "0"
      ],
      "description": "Require verified video views. Defaults to false; optional mode skips view-only recovery."
    }
  },
  "nullable": true,
  "required": [
    "url"
  ]
}

GET/status

Get the current public status of every Project API API capability.

{}

GET / POST/tiktok/channel-videos

Get recent TikTok videos with bounded recovery. Paid requests allow up to 120 seconds; failures use zero credits.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL of the resource"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from a previous response"
    },
    "access_key": {
      "type": "string",
      "description": "Project access key (also accepted as x-access-key header)"
    },
    "cache": {
      "type": "boolean",
      "description": "Opt in to successful response caching; cache hits use zero credits."
    },
    "cache_ttl": {
      "type": "integer",
      "minimum": 60,
      "maximum": 2592000,
      "description": "Maximum response age in seconds. Default 86400; no stale fallback."
    },
    "no_cache": {
      "type": "boolean",
      "description": "Bypass all extraction and result caches."
    },
    "country": {
      "type": "string",
      "description": "Residential exit country (two-letter code)."
    }
  },
  "nullable": true,
  "required": [
    "url"
  ]
}

GET / POST/tiktok/search

Search TikTok videos by keyword.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results"
    },
    "access_key": {
      "type": "string",
      "description": "Project access key (also accepted as x-access-key header)"
    }
  },
  "nullable": true,
  "required": [
    "query"
  ]
}

GET / POST/tiktok/stats

Get engagement metrics and metadata for a TikTok video.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL of the resource"
    },
    "access_key": {
      "type": "string",
      "description": "Project access key (also accepted as x-access-key header)"
    }
  },
  "nullable": true,
  "required": [
    "url"
  ]
}

GET / POST/youtube/transcript

Extract the full transcript (with timestamps) from a YouTube video or Short.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Full URL of the resource"
    },
    "access_key": {
      "type": "string",
      "description": "Project access key (also accepted as x-access-key header)"
    },
    "no_cache": {
      "type": "boolean",
      "description": "Bypass transcript extraction and summary-result caches."
    }
  },
  "nullable": true,
  "required": [
    "url"
  ]
}