# submit_query

Submit Query · v1.1.0 · curated

Submit a heavy/long-running query to run OFF the request path and get a job_id back immediately, instead of blocking (and risking a timeout) on a statewide/cross-hospital scan. Arguments are validated against the target tool's own input model AT ACCEPT TIME, so a malformed submit is refused immediately (reason=invalid_arguments) instead of after you waited for the job. A POINT-LOOKUP CALL IS REFUSED, not queued: the refusal carries the direct call to make instead, with your own arguments already in it. That includes a bounded compare_hospital_rates read (one billing_code + one state), which the precomputed window answers in about a second. Pass force=true only when the SYNC door sent you here (too_large_for_sync, tool_timeout) — that route is always accepted. Poll with poll_query(job_id) and read the result with fetch_query(job_id). A refusal names the async-eligible targets and their current serving state, so you always know what this lane can run today.

**Inputs.**
- `tool` (required): 
- `arguments`: 
- `force`: 

**A real answer** (customer seat, 0.48 s, args `{"tool":"prove_commercial_price","arguments":{"payer":"cigna","version_id":"2026-05","state":"CT","code":"99213"}}`):

```json
{
 "status": "refused",
 "refusal": {
  "code": "PLAN_REQUIRED",
  "message": "Vlada answers questions; it does not export whole tables. Ask for the aggregate you need (group, filter or rank in SQL). Paging past the first page and the bulk lane are not on the free or Studio plans; for whole-table or bulk work, write to ben@vladahealth.com.",
  "recover_with": [
   {
    "tool": "query_substrate",
    "arguments_hint": {
     "sql": "SELECT <dimensions>, COUNT(*), AVG(<measure>) FROM <table> WHERE <narrow filters> GROUP BY <dimensions> ORDER BY 2 DESC LIMIT 50"
    },
    "note": "Group, filter or rank in SQL so the engine computes over the full set and returns the answer in a few rows. Paging past the first page and the bulk lane are not on the free or Studio plans; for whole-table or bulk work, write to ben@vladahealth.com."
   }
  ],
  "detail": {
   "tier": "grandfathered",
   "reason": "bulk_lane_requires_pro",
   "rows_per_call": 500,
   "upgrade_url": "https://www.vladahealth.com/upgrade"
  }
 },
 "as_of": "2026-11-09",
 "error": {
  "code": "plan_required",
  "message": "Vlada answers questions; it does not export whole tables. Ask for the aggregate you need (group, filter or rank in SQL). Paging past the first page and the bulk lane are not on the free or Studio plans; for whole-table or bulk work, write to ben@vladahealth.com.",
  "reason": "bulk_lane_requires_pro",
  "upgrade_url": "https://www.vladahealth.com/upgrade"
 }
}
```

REST: `POST https://api.vladahealth.com/v1/tools/submit_query` with the inputs as the JSON body. MCP: the tool by name.