Skip to content
EN
Get API key
Browse documentation

API reference

MCP tools and schemas

Look up FlashData MCP tool arguments, defaults, account reads, job states and result retrieval.

On this page

Markdown version

OAuth, Codex, OpenClaw and API-key access options

Choose your MCP client and connect

Transport and authentication

The hosted MCP endpoint uses Streamable HTTP. API-key connections send X-API-Key; tool access follows the key's source permissions and available credits.

Streamable HTTP
URL: https://data.flashdata.dev/mcp
X-API-Key: <your API key>

Store your actual FlashData API key in the client’s credential configuration. Do not put it in a conversation or tool arguments. This section covers API-key connections; the agent access guide covers OAuth login and the tested Codex and OpenClaw configurations. youtube_download supports asynchronous media downloads with the appropriate API-key permission.

Manage API keys

Query tools

Your client discovers the tools granted by the key. All six Google and eight YouTube data tools default to realtime and also accept mode: async. submit_batch supports both groups. youtube_download uses the formal Download API, requires customer storage, and supports async jobs or submit_batch. The model can choose and combine tools for the task.

Google

google_search · google_images · google_news · google_shopping · google_videos · google_places

YouTube

youtube_search · youtube_search_extended · youtube_metadata · youtube_transcript · youtube_captions · youtube_trainability · youtube_channel · youtube_suggestions · youtube_download

google_search · arguments JSON
{
  "query": "MCP protocol",
  "num": 3,
  "gl": "us",
  "hl": "en",
  "mode": "async"
}

Tool arguments

Put query fields such as query, num, language and mode directly in the tool’s arguments object, without the REST API’s params wrapper. A query tool’s name selects its source; only entries in submit_batch need source. API keys and callback_url are not tool arguments. The JSON examples below are argument objects for client.callTool({ name, arguments }).

Use JSON booleans and integer numbers, not strings. Unknown fields are rejected. The 14 data query tools accept mode: realtime or async, defaulting to realtime. Batch entries do not accept mode.

ToolRequiredOptional arguments & defaults
youtube_downloadvideo_id, storagemode supports async only (default). download_type: audio_video (default)/video/audio. video_quality: <=720 by default; best/worst or <=, ==, >= with 144/360/480/720/1080/1440/2160/4320. fps: the same comparisons with 1–240. output_format: mp4 (default)/webm/mkv for video, m4a (default)/mp3/opus for audio. audio_language: default/original; audio_quality: best/320/256/192/128, audio only. yt_dlp_format: up to 1024 characters, overrides quality, fps and language selection. Omit video_quality/fps for audio and audio_language for video-only. storage is required and matches Download API params.storage. start_at/end_at: HH:MM:SS, up to 12 hours; end_at must follow start_at. upload_metadata: boolean, default false. Every batch download needs storage. No browser_delivery or callback_url.
storagestorage_type, storage_urlstorage_url is your bucket name (Azure: container), not a local directory. storage_type: s3/s3_compatible/oss/gcs/azure/cos/bos/tos; optional object_prefix. S3, S3-compatible, OSS, COS, BOS and TOS use access_key/secret_key with the applicable region/endpoint_url. GCS uses service_account (project_id, client_email, private_key); Azure uses account_name and a container sas_token with write permission. The endpoint must be reachable from the Worker. Read credentials from your storage configuration; do not paste them into chat or echo them.
google_*queryquery: 1–2,000 characters. gl: two-letter country; hl: 1–35 character language code; location/tbs: 1–200 characters; num/page: integers 1–100; autocorrect: boolean. Omitted options use the search provider’s behavior, with no fixed country, language or result count guaranteed.
youtube_searchqueryquery: 1–2,000 characters. max_results: 1–20, default 20; filters: filter object, omitted or null for no filters.
youtube_search_extendedqueryquery: 1–2,000 characters. max_results: 1–700, default 20; filters: same as standard search.
youtube_metadatavideo_idinclude_formats and include_chapters: booleans, both default true.
youtube_transcriptvideo_idOmit language to prefer en-orig, then en, returning one track. With auto=true, each code prefers its -orig track, then the plain code; explicit -orig and auto=false stay exact. Arrays try all 1–10 requested languages and return tracks and errors in order. auto defaults to true for automatic captions.
youtube_captionsvideo_idOmit language to prefer en-orig, then en, returning one track. With auto=true, each code prefers its -orig track, then the plain code; explicit -orig and auto=false stay exact. Arrays try all 1–10 requested languages and return tracks and errors in order. auto defaults to false for uploader-provided captions.
youtube_trainabilityvideo_idNo optional arguments except mode. Reports Creative Commons license classification; it does not grant training permission.
youtube_channelhandlehandle: 1–100 characters; video_limit: 1–100, default 20.
youtube_suggestionsqueryquery: 1–2,000 characters; language: default en; region: two-letter country code, default US.

video_id is an 11-character YouTube ID using letters, numbers, underscores or hyphens; supply the ID rather than the video URL. Each language code is 1–35 characters using letters, numbers or hyphens. For subtitles, auto=true selects automatic captions and false selects uploader-provided captions, with no automatic fallback between them. For language arrays, check errors even when the job succeeds.

YouTube search filters

filters.type: video/channel/playlist/movie; upload_date: today/last_hour/this_week/this_month/this_year; duration: <4, 4-20 or >20; sort_by: rating/relevance/view_count/upload_date. Feature flags are booleans; true requires that feature: 360, 3d, 4k, creative_commons, hd, hdr, live, location, purchased, subtitles, vr180.

youtube_search · arguments JSON
{
  "query": "renewable energy",
  "max_results": 5,
  "filters": {
    "type": "video",
    "duration": "<4",
    "subtitles": true
  }
}

Account insights (free)

get_balance reads your shared account balance; get_pricing estimates query costs; get_limits reads plan limits and current pending jobs; get_usage summarizes the last 7 days by default, with a maximum 31-day window. Usage includes all account keys for sources authorized by the calling key and may be delayed.

get_balance and get_limits take {}. get_pricing accepts an optional source; omit it for all MCP query sources authorized by your key. request_count is an integer from 1 to 100000, default 1; each page or batch item counts as a separate request. get_usage accepts an optional source; omit it for all authorized sources. It includes youtube_download usage. Download pricing returns creditsPerTb (1 TB = 10^12 bytes); downloads reserve Credits and settle by actual uploaded bytes. request_count does not apply to downloads and estimatedCredits is null.

get_usage from/to must be UTC ISO timestamps such as 2026-09-21T00:00:00Z, optionally with 1–3 fractional second digits. from is inclusive, to exclusive, rounded down to minutes. The default window is 7 days and the maximum is 31 days. With only from, to is seven days later; with only to, from is seven days earlier. Read the response’s from/to for the effective window.

get_pricing · arguments JSON
{
  "source": "google_search",
  "request_count": 3
}
get_usage · arguments JSON
{
  "source": "youtube_metadata",
  "from": "2026-09-21T00:00:00Z",
  "to": "2026-09-22T00:00:00Z"
}

Jobs and large results

An async request returns a job id; pass it as job_id to get_job to read job.status. Completed jobs include the original query response in output. For downloads, output is the upload manifest: output.results[0].file_url points to customer storage, with file_size, downloaded_bytes and md5. Private files require your storage authentication. JSON results are retained for 24 hours; media retention and access follow your storage policies. submit_batch accepts at least one Google or YouTube query (including downloads), with source and flat arguments on each entry. Each entry is billed separately, and your plan’s batch and pending limits apply. Reading jobs does not charge again. File-based Bulk is not an MCP tool.

Processing an ID file? Use the Bulk HTTP API

youtube_transcript · arguments JSON
{
  "video_id": "FUfGcZ092b0",
  "language": "en",
  "auto": true,
  "mode": "async"
}
submit_batch · arguments JSON
{
  "queries": [
    {
      "source": "google_search",
      "query": "renewable energy",
      "num": 3
    },
    {
      "source": "youtube_metadata",
      "video_id": "FUfGcZ092b0",
      "include_formats": false
    }
  ]
}

Replace the example job_id, result_id and offset with values from your response. Read the next chunk without resubmitting the query.

get_job · arguments JSON
{
  "job_id": "job_REPLACE_WITH_RETURNED_ID"
}

Large responses include a JSON text chunk, result_id and next_offset. Call get_result with the same key and the returned result_id. offset is a nonnegative integer, default 0; use the previous next_offset to continue. limit is an integer from 1 to 16000, default 16000, measured in UTF-16 code units rather than bytes or result rows. Concatenate chunks in order before parsing JSON; next_offset=null marks the end. Results are cached for 10 minutes, with at most four large results per key, and may be evicted sooner. Reading chunks does not repeat the query or charge Credits.

get_result · arguments JSON
{
  "result_id": "result_1800000000000_00000000-0000-0000-0000-000000000000",
  "offset": 16000,
  "limit": 16000
}

Billing and errors

Queries use your existing plan’s Credits pricing with no additional MCP charge. Tool errors set isError and retain the upstream HTTP status and request ID. Restore Credits for insufficient balance and check key permissions for access errors.

A timeout or lost connection does not mean the query was not executed. For query_outcome_unknown, check Request History in the console before deciding to submit again. Do not automatically retry paid submissions; reads of existing jobs or chunks can be retried. Upstream responses are limited to 4 MiB, so limit search size; oversized responses may already have been charged.

Underlying HTTP status codes · Retry rules

Verify with a JavaScript client

This client uses the verified official SDK 1.30.0 to connect over Streamable HTTP and list tools without running a paid query. Save it as mcp-check.mjs, set FLASHDATA_API_KEY in your environment, then run node mcp-check.mjs.

npm
npm install @modelcontextprotocol/[email protected]
mcp-check.mjs
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const key = process.env.FLASHDATA_API_KEY;
if (!key) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new Client({ name: 'my-app', version: '1.0.0' });
try {
  await client.connect(new StreamableHTTPClientTransport(
    new URL('https://data.flashdata.dev/mcp'),
    { requestInit: { headers: { 'X-API-Key': key } } }
  ));
  console.log((await client.listTools()).tools.map(tool => tool.name));
} finally {
  await client.close();
}