canonical: https://jentic.com/apis/flashdata.dev/flashdata

# FlashData Customer API

The FlashData Customer API runs Google search, image, news, shopping, video, and places queries and pulls YouTube search results, video metadata, transcripts, captions, and media downloads. Queries go to the data host either in realtime, returning results in the same response, or as background jobs whose results you download once complete, with batch submission for several queries at once. Bulk jobs take an uploaded file of YouTube video IDs and process them for metadata, transcripts, captions, or downloads, with pause, resume, and cancel controls. The same API also covers the account side: API key creation and rotation, credit balance and pricing, usage reporting, completion webhooks, and Stripe-backed billing.

## For AI agents

Run Google search and YouTube queries in realtime or as background jobs, fetch transcripts and video metadata, and check balance, pricing, and usage with a FlashData API key.

## Scope

Does not crawl arbitrary websites, upload videos to YouTube, or manage Google Ads campaigns. Use for Google search and YouTube data queries and the FlashData account that pays for them only.

## Capabilities

- Run a realtime Google search with the `google_search` source and optional gl and hl country and language params
- Fetch a YouTube transcript or captions for a `video_id`, preferring the original-language track
- Submit background queries, including batches billed separately, and download each job's results when done
- Create a bulk job for an uploaded file of YouTube IDs, then start, pause, resume, or cancel it
- Check the API key's live balance, per-source pricing, plan limits, and usage before spending credits
- Register a completion webhook URL and send it a sample download-complete payload to test delivery

## Use cases

### AI agent web and video research

A research agent needs fresh Google results and YouTube transcripts to answer a question. Through Jentic it searches for 'search Google for a keyword', loads the realtime query operation, and posts a body with a source such as google_search or youtube_transcript while the X-API-Key header is injected at call time. Results come back in the same response as JSON or plain text, so the agent can read them without polling.

Example prompt: POST `/v1/queries/realtime` with source google_search, query 'self-hosted agent gateway', and params gl 'us' and hl 'en', then summarise the top organic results

### Bulk YouTube transcript extraction

Building a dataset from many videos means processing a long list of IDs without one request per video. A FlashData bulk job is created with a source such as youtube_transcript, returns a file upload URL for the ID list, and is then started. Progress and aggregate counts are readable while it runs, it can be paused or resumed, and completed output arrives as a manifest plus gzip-compressed NDJSON result parts.

Example prompt: POST /bulk-jobs with source youtube_transcript, upload the ID file to the returned URL, call POST `/bulk-jobs/{bulkId}/start`, then poll GET `/bulk-jobs/{bulkId}` until done and fetch GET `/bulk-jobs/{bulkId}/results`

### Cost-aware query planning

Before running a large batch, an agent should confirm it can pay for it. FlashData exposes the calling key's authorized sources, live account balance, actual per-source prices for a given request_count, plan limits with current pending jobs, and usage over a from and to window. The agent can stop or downsize a job before credits run out.

Example prompt: Call GET `/api-access/pricing` with source youtube_metadata and request_count 500, compare it with GET `/api-access/balance`, and only submit the batch if the balance covers it

### Background queries with webhook delivery

Large or slow queries such as media downloads run better in the background. A query submitted to the async endpoint returns job links, a saved completion callback URL is notified when the job finishes, and the result is downloaded from the job's results endpoint. Webhooks can be tested with a sample download-complete payload before relying on them.

Example prompt: POST `/v1/queries` with source youtube_download, a video_id, and params download_type 'audio', then wait for the job and fetch GET `/jobs/{jobId}/results`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/queries/realtime` | Run a query and get results in the same response |
| POST | `/v1/queries` | Submit a background query |
| POST | `/v1/queries/batch` | Submit several background queries |
| GET | `/jobs/{jobId}/results` | Download a completed async result |
| POST | `/bulk-jobs` | Create a bulk YouTube job and get an upload URL |
| GET | `/bulk-jobs/{bulkId}` | Read bulk job progress |
| GET | `/api-access/balance` | Read the live account balance |
| GET | `/api-access/pricing` | Read per-source prices for the key |

## Key resources

- **Data queries** — Google and YouTube queries run in realtime, in the background, or as a batch
- **Jobs** — Background query jobs with status and downloadable results
- **Bulk jobs** — File-driven YouTube jobs with start, pause, resume, cancel, and NDJSON result parts
- **API access** — The calling key's sources, balance, pricing, limits, and usage
- **API keys** — Key metadata, creation, rotation, and revocation from a browser session
- **Delivery webhooks** — Completion callback URLs and test deliveries

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 70 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 77 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 67 / 100
  - Agent Usability: 87 / 100
  - Security: 56 / 100
  - AI Discoverability: 69 / 100
- **View full report:** https://jentic.com/apis/flashdata.dev/flashdata/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring FlashData by hand means splitting calls between the management host and the data host, sending X-API-Key on queries while console endpoints expect a browser session and CSRF token, and choosing realtime, background, or batch submission. Through Jentic you install once, import FlashData from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** FlashData carries the query source inside the request body, so rules bound which operations your agent may call, not which source it queries; the key's own source scopes cover that side. You choose the operations it may call, so destructive ones like cancelling a bulk job or revoking an API key are not included unless you add them.
- **Credential handling:** Your FlashData API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get a YouTube transcript' or 'search Google for a keyword', and Jentic returns the matching FlashData operation with its input schema, including the per-source query shape.

## Related APIs

- **SearchAPI Google Search** — Realtime Google and other search engine results
- **serpstack** — Google search results as JSON
- **GetYouTubeTranscript** — Fetch transcripts for YouTube videos
- **Apify** — Run web scrapers and crawlers for sites beyond search and YouTube

## FAQ

### What authentication does the FlashData Customer API use?

Per its OpenAPI spec, data queries and the api-access endpoints use an API key in the `X-API-Key` header, and job access is restricted to the key's source scopes. Console endpoints such as API key management and billing use the `__Host-fd_session` browser cookie, with an `X-CSRF-Token` header on writes, and the agent-connection onboarding flow uses short-lived bearer proofs and setup credentials. Public endpoints such as health, status, plans, and the list of public data sources need no credential. Through Jentic your API key is stored by your own instance and injected at call time.

### Can I get Google search results and YouTube transcripts from the same FlashData API?

Yes. The realtime and background query endpoints accept a body whose source selects the data, including google_search, google_images, google_news, google_shopping, google_videos, google_places, youtube_search, youtube_metadata, youtube_transcript, and youtube_captions. Transcript queries take an 11-character video_id and an optional language param.

### What are the rate limits for the FlashData Customer API?

The OpenAPI spec notes that rate limits apply but does not state numeric limits. Your agent can read the account's plan limits and current pending jobs from GET `/api-access/limits`, and FlashData's guides at https://flashdata.dev/docs cover current limits.

### Is there a FlashData MCP server?

You don't need an MCP server to give your agent FlashData. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent discovers the query, job, and balance operations on demand instead of loading a full tool list into its context.

### How do I run a Google search with FlashData through Jentic?

Search Jentic for 'search Google for a keyword', load the realtime query operation, and execute POST `/v1/queries/realtime` with source google_search and your query, adding gl and hl params for country and language when needed. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with FlashData?

Yes. Write a rule that allows POST `/v1/queries/realtime`, GET `/api-access/balance`, and GET `/api-access/pricing` only, and the agent can run searches and check what they cost but cannot start bulk jobs or download results from other jobs. Pair it with a FlashData key whose source scopes cover only the sources you want, and every call the agent makes is logged.

### How do I know when a background FlashData job is finished?

Save a completion callback URL with POST `/delivery/webhooks` and FlashData calls it when a job completes, or poll GET `/jobs/{jobId}` with your API key. Once done, download the result from GET `/jobs/{jobId}/results`, or for bulk jobs the manifest and parts under GET `/bulk-jobs/{bulkId}/results.`
