---
title: "Submit a background query and follow its job links"
method: POST
path: "/v1/queries"
tags: ["Data Queries"]
---

# Submit a background query and follow its job links

`POST /v1/queries`

## Request

- Base URL: `https://data.flashdata.dev`
- URL: `https://data.flashdata.dev/v1/queries`
- Auth: API key in header `X-API-Key`

## Request body

- union
  - AsyncQueryGoogleSearch: Google Search. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'google_search', required
    - `query` string, required
    - `params` object
      - `gl` string: Country code. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `hl` string: Interface language. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `location` string
      - `num` integer: Requested result count. Actual count varies by query and search type; no fixed value is added when omitted.
      - `page` integer: Requested page. Set explicitly for pagination; each page is a separate query.
      - `tbs` string
      - `autocorrect` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryGoogleImages: Google Images. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'google_images', required
    - `query` string, required
    - `params` object
      - `gl` string: Country code. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `hl` string: Interface language. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `location` string
      - `num` integer: Requested result count. Actual count varies by query and search type; no fixed value is added when omitted.
      - `page` integer: Requested page. Set explicitly for pagination; each page is a separate query.
      - `tbs` string
      - `autocorrect` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryGoogleNews: Google News. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'google_news', required
    - `query` string, required
    - `params` object
      - `gl` string: Country code. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `hl` string: Interface language. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `location` string
      - `num` integer: Requested result count. Actual count varies by query and search type; no fixed value is added when omitted.
      - `page` integer: Requested page. Set explicitly for pagination; each page is a separate query.
      - `tbs` string
      - `autocorrect` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryGoogleShopping: Google Shopping. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'google_shopping', required
    - `query` string, required
    - `params` object
      - `gl` string: Country code. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `hl` string: Interface language. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `location` string
      - `num` integer: Requested result count. Actual count varies by query and search type; no fixed value is added when omitted.
      - `page` integer: Requested page. Set explicitly for pagination; each page is a separate query.
      - `tbs` string
      - `autocorrect` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryGoogleVideos: Google Videos. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'google_videos', required
    - `query` string, required
    - `params` object
      - `gl` string: Country code. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `hl` string: Interface language. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `location` string
      - `num` integer: Requested result count. Actual count varies by query and search type; no fixed value is added when omitted.
      - `page` integer: Requested page. Set explicitly for pagination; each page is a separate query.
      - `tbs` string
      - `autocorrect` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryGooglePlaces: Google Places. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'google_places', required
    - `query` string, required
    - `params` object
      - `gl` string: Country code. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `hl` string: Interface language. Set explicitly when needed; omitted values use the search provider’s behavior.
      - `location` string
      - `num` integer: Requested result count. Actual count varies by query and search type; no fixed value is added when omitted.
      - `page` integer: Requested page. Set explicitly for pagination; each page is a separate query.
      - `tbs` string
      - `autocorrect` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeSearch: YouTube Search. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_search', required
    - `query` string, required
    - `params` object
      - `max_results` integer
      - `filters` object, nullable
        - `360` boolean
        - `duration` '<4' | '4-20' | '>20'
        - `sort_by` 'rating' | 'relevance' | 'view_count' | 'upload_date'
        - `type` 'video' | 'channel' | 'playlist' | 'movie'
        - `upload_date` 'today' | 'last_hour' | 'this_week' | 'this_month' | 'this_year'
        - `3d` boolean
        - `4k` boolean
        - `creative_commons` boolean
        - `hd` boolean
        - `hdr` boolean
        - `live` boolean
        - `location` boolean
        - `purchased` boolean
        - `subtitles` boolean
        - `vr180` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeSearchExtended: YouTube Extended Search. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_search_extended', required
    - `query` string, required
    - `params` object
      - `max_results` integer
      - `filters` object, nullable
        - `360` boolean
        - `duration` '<4' | '4-20' | '>20'
        - `sort_by` 'rating' | 'relevance' | 'view_count' | 'upload_date'
        - `type` 'video' | 'channel' | 'playlist' | 'movie'
        - `upload_date` 'today' | 'last_hour' | 'this_week' | 'this_month' | 'this_year'
        - `3d` boolean
        - `4k` boolean
        - `creative_commons` boolean
        - `hd` boolean
        - `hdr` boolean
        - `live` boolean
        - `location` boolean
        - `purchased` boolean
        - `subtitles` boolean
        - `vr180` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeMetadata: YouTube Metadata. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_metadata', required
    - `video_id` string, required
    - `params` object
      - `include_formats` boolean
      - `include_chapters` boolean
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeTranscript: YouTube Transcript. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_transcript', required
    - `video_id` string, required
    - `params` object
      - `language` string
      - `auto` boolean: true selects automatically generated captions; false selects manually provided captions. Does not fall back between the two.
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeCaptions: YouTube Captions. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_captions', required
    - `video_id` string, required
    - `params` object
      - `language` string
      - `auto` boolean: true selects automatically generated captions; false selects manually provided captions. Does not fall back between the two.
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeTrainability: YouTube Trainability. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_trainability', required
    - `video_id` string, required
    - `params` object
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeChannel: YouTube Channel. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_channel', required
    - `handle` string, required
    - `params` object
      - `video_limit` integer
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeSuggestions: YouTube Suggestions. Supported modes: realtime, async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_suggestions', required
    - `query` string, required
    - `params` object
      - `language` string
      - `region` string
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.
  - AsyncQueryYoutubeDownload: YouTube Download. Supported modes: async, batch. Provider-specific storage requirements and conditional media options are validated by the server; see the source reference.
    - `source` 'youtube_download', required
    - `video_id` string, required
    - `params` object, required
      - `download_type` 'audio_video' | 'video' | 'audio'
      - `video_quality` 'best' | 'worst' | '<=144' | '==144' | '>=144' | '<=360' | '==360' | '>=360' | '<=480' | '==480' | '>=480' | '<=720' | '==720' | '>=720' | '<=1080' | '==1080' | '>=1080' | '<=1440' | '==1440' | '>=1440' | '<=2160' | '==2160' | '>=2160' | '<=4320' | '==4320' | '>=4320'
      - `fps` string
      - `audio_language` 'default' | 'original'
      - `audio_quality` 'best' | '320' | '256' | '192' | '128'
      - `yt_dlp_format` string
      - `upload_metadata` boolean
      - `output_format` 'mp4' | 'webm' | 'mkv' | 'm4a' | 'mp3' | 'opus'
      - `start_at` string
      - `end_at` string
      - `storage` object, required: Customer-owned destination, using the same fields as Download API params.storage. Supply credentials from your configured storage; do not invent values or display secrets. GCS uses service_account; Azure uses account_name and a container SAS with write permission; other providers use access_key/secret_key and provider endpoint/region as needed.
        - `storage_type` 'azure' | 'bos' | 'cos' | 'gcs' | 'oss' | 's3' | 's3_compatible' | 'tos', required
        - `storage_url` string, required: Bucket name (Azure: container name). Not a local path or a full object URL.
        - `object_prefix` string: Optional object folder prefix. Use a distinct prefix when keeping multiple versions of a video.
        - `access_key` string
        - `secret_key` string
        - `endpoint_url` string: Provider endpoint, required for S3-compatible storage. Must be reachable from the download Worker.
        - `region` string
        - `account_name` string
        - `sas_token` string: Azure container SAS with write permission; never return this secret to the user in output.
        - `service_account` object
          - `project_id` string, required
          - `client_email` string, required
          - `private_key` string, required
    - `callback_url` string, nullable: Async and batch only. Public HTTPS URL on port 443 without credentials or a fragment. Omit, null or empty string disables callbacks. Server validates public reachability.

## Response `200`

Successful response

- AsyncSubmission
  - `id` string
  - `source` string
  - `status` string
  - `created_at` string, date-time
  - `links` JobLink[]
    - `rel` 'self' | 'results' | 'content' | 'download', required
    - `href` string, uri, required
    - `method` 'GET', required
    - `expires_at` string, date-time
    - `filename` string
    - `content_type` string
    - `size_bytes` integer
  - `usage` object
    - `credits` number

## Other responses

- `default`: Query rejected or upstream unavailable. Inspect the HTTP status, code and message; see /docs/errors.

---

[API](https://skmtc.dev/flashdata/apis/flashdata-customer-api.md) · [All operations](https://skmtc.dev/flashdata/apis/flashdata-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flashdata/apis/flashdata-customer-api/revisions/109179fe9313?raw)