---
title: "Submit multiple background queries; each is billed separately"
method: POST
path: "/v1/queries/batch"
tags: ["Data Queries"]
---

# Submit multiple background queries; each is billed separately

`POST /v1/queries/batch`

## Request

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

## Request body

- object
  - `queries` union[], required: Maximum size and pending-job admission depend on your account's current plan.
    - 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
              - …
        - `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

- object
  - `queries` 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
  - `total_credits` number
  - `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)