Skip to content
EN
Get API key
Browse documentation

API reference

Response formats

Choose structured JSON for your application or Markdown content for an AI agent. Control the response with two headers.

On this page

Choose a format

JSON with original result fields is the default. Accept selects JSON or plain text; X-Respond-With: markdown converts the result content to Markdown. Your request body stays JSON.

ResponseAcceptX-Respond-WithUse for
JSONapplication/jsonOmitParsing fields in code · default
JSON + Markdownapplication/jsonmarkdownAgent context with structured metadata
Plain texttext/plainOmitReading original fields in a terminal
Text + Markdowntext/plainmarkdownReading metadata and Markdown together

Request and response examples

These tabs show the same Google Search in each format. Use Bash and cURL 7.76+ with FLASHDATA_API_KEY set to a key that allows google_search. Running a command submits one billable search.

Default. Parse the results array; the fields inside it depend on the source.

Request · cURL / Bash
curl --fail-with-body --silent --show-error \
  'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"source":"google_search","query":"vector databases"}'
Example response · illustrative values
{
  "source": "google_search",
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Example page",
          "link": "https://example.com/article",
          "snippet": "A short source snippet."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-10-22T12:00:00.000Z"
}

Supported endpoints

The same rules apply to Google Search and YouTube query sources. For YouTube Download, they format the delivery record, not the video or audio bytes. Account APIs, Bulk manifests and NDJSON parts, callbacks and MCP responses use their own formats.

EndpointJSON / plain textMarkdown content
POST /v1/queries/realtimeSupportedSupported
GET /v2/jobs/{id}/resultsSupportedSupported
POST /v1/queriesSubmission receiptIgnored — select it when reading results
POST /v1/queries/batchSubmission receiptIgnored — select it when reading results
GET /v2/jobs/{id}Job statusIgnored — no result content here

Format a completed job result

Set the headers when reading the result, even if you set them at submission. Set JOB_ID to a completed job you can access. This GET reads existing results without submitting another query.

Requested formatResult response
Original JSON302 with a signed storage URL in Location. Fetch that URL separately, without X-API-Key. Stored results may be gzip-compressed.
Plain text or either Markdown option200 with the formatted body directly in the response.
Retrieve Markdown inside JSON · cURL / Bash
curl --fail-with-body --silent --show-error \
  "https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}/results" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json' \
  --header 'X-Respond-With: markdown'

Format errors

API errors remain JSON or application/problem+json, even when you request plain text. Check the HTTP status before parsing the success format.

Status / codeFix
400 · unsupported_representationUse X-Respond-With: markdown or omit the header. Values such as json or text are not supported.
406 · not_acceptableUse Accept: application/json or text/plain. text/markdown and application/xml are not supported.

Accept header details

Omit Accept or send */* to get JSON. Responses use UTF-8. Media ranges and q weights are supported; an unsupported charset returns 406 unless another acceptable range matches. Content-Type: application/json describes the request body, not the response.

Prefer text, allow JSON
Accept: text/plain; charset=utf-8, application/json;q=0.8