Execute Kagi API requests and save JSON responses

Execute one or more kagiPro query objects against the Kagi API and write raw JSON responses to disk. This function supports search, enrich (web/news), summarize, and FastGPT query classes generated by query_search(), query_enrich_web(), query_enrich_news(), query_summarize(), and query_fastgpt().

Usage

kagi_request(
  connection,
  query,
  limit = NULL,
  output = NULL,
  overwrite = FALSE,
  append = FALSE,
  workers = 1,
  verbose = FALSE,
  error_mode = c("stop", "write_dummy"),
  metadata_request_args = list()
)

Arguments

connection: A kagi_connection() object.
query: A query object of class kagi_query_search, kagi_query_summarize, kagi_query_enrich_web, kagi_query_enrich_news, kagi_query_fastgpt, or a list of such objects.
limit: Optional integer limit used for search and enrich endpoints.
output: Directory where JSON response files are written.
overwrite: Logical. If TRUE, existing output is deleted before writing.
append: Logical. If TRUE, write into an existing output directory instead of deleting it.
workers: Number of parallel workers to use when query is a list.
verbose: Logical indicating whether progress messages should be shown.
error_mode: Error handling mode. "stop" (default) throws on request errors. "write_dummy" writes a fallback JSON payload and returns output.
metadata_request_args: Optional named list persisted in replay metadata (request_args) for each query. Intended for higher-level orchestrators.

Value

The normalized path to output.

Details

If query is a list of query objects, requests are executed in parallel (using workers) and each query is written into a named subdirectory under output.

Files are written as {endpoint}_{page}.json (for example search_1.json). Pagination is handled via meta$next_cursor when provided by the API.

Query replay metadata is written alongside JSON outputs:

per query folder: _query_meta.json