{
  "slug": "stripe-reporting-query-runs-creates-and-retrieves-ad-hoc-queries-93f1e962926d",
  "title": "stripe reporting query-runs creates and retrieves ad hoc queries",
  "tools": [
    "stripe-cli"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-07-09T21:07:25.000Z",
  "announced_at": "2026-07-09T21:07:25.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "When running an ad hoc SQL query against Stripe data, create a query run with exactly one SQL source, then retrieve its ID to check status and access the result download URL.",
    "examples": [
      "stripe reporting query-runs create --sql \"<SQL>\"",
      "stripe reporting query-runs create --sql-file <path> [--compress-file] [--dry-run] [--live]",
      "stripe reporting query-runs retrieve <id> [--live]"
    ],
    "gotchas": [
      "Version: v1.43.7",
      "Availability: The API is in public preview.",
      "--sql (required): SQL query text; required unless --sql-file is set. Mutually exclusive with --sql-file.",
      "--sql-file <path> (required): Read SQL from a file; use `-` to read stdin. Required unless --sql is set; mutually exclusive with --sql.",
      "--compress-file: Compress the result file; sets `result_options.compress_file` to true.",
      "--dry-run: Preview the request without sending it.",
      "--live: Make a live request; default is test mode.",
      "<id> (required): ID of the query run to retrieve.",
      "result_options.compress_file: Boolean set to true by `--compress-file`; the source documents no alternative sub-keys or allowed values.",
      "Prerequisite: A Stripe API key must be available through the selected CLI profile; the command reads the profile's test or live API key.",
      "Prerequisite: The endpoint is a preview API; the CLI marks both commands as preview commands and sets the preview Stripe-Version header automatically.",
      "The request builder sets `Stripe-Version: 2026-06-24.preview` and JSON content-type automatically.",
      "Retrieve polls query status (`running` → `succeeded`/`failed`) and fetches the result download URL."
    ]
  },
  "why_it_matters": "Run and inspect an ad hoc SQL query against Stripe data from the CLI.",
  "before": "The CLI could retrieve Sigma scheduled queries through the older `/v1/sigma` endpoint, but could not start new or ad hoc queries.",
  "sources": [
    "https://github.com/stripe/stripe-cli/releases/tag/v1.43.7",
    "https://github.com/stripe/stripe-cli/pull/1737",
    "https://github.com/stripe/stripe-cli/blob/v1.43.7/pkg/cmd/reporting.go"
  ],
  "rank": 0.99032,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v2+judge-v2x3+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "wave1b-20261016",
    "verdict_id": "wave1b-20261016:wave1b-20261016-d4bda53adf7bd138-1:gate",
    "evidence_hash": "70e4116a15c0b7007d2055879e547e5218c672fa82b81a8fcab7232229a91eb4"
  },
  "review": {
    "draft_hash": "dc651c8f594d7340d447cc1a3dd6b099a5d8a19ace8aa8100cfa32c42c78ba54",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "wave1b-20261016:gate",
    "reason": "3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.99 >= 0.9; 2 needed) and Jev gave 0.81 (>= 0.6 needed)."
  }
}