submit_query

What it answers

1. 1Submit 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.
2. 2Arguments 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.
3. 3A POINT-LOOKUP CALL IS REFUSED, not queued: the refusal carries the direct call to make instead, with your own arguments already in it.
4. 4That includes a bounded compare_hospital_rates read (one billing_code + one state), which the precomputed window answers in about a second.
5. 5Pass force=true only when the SYNC door sent you here (too_large_for_sync, tool_timeout) — that route is always accepted.
6. 6Poll with poll_query(job_id) and read the result with fetch_query(job_id).
7. 7A refusal names the async-eligible targets and their current serving state, so you always know what this lane can run today.

Inputs (3)

Call it

# MCP (https://mcp.vladahealth.com/mcp): the tool by name
submit_query(tool="prove_commercial_price", arguments={"payer":"cigna","version_id":"2026-05","state":"CT","code":"99213"})

curl -X POST https://api.vladahealth.com/v1/tools/submit_query \
  -H "Authorization: Bearer $VLADA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"prove_commercial_price","arguments":{"payer":"cigna","version_id":"2026-05","state":"CT","code":"99213"}}'

# the schema, no key
curl https://api.vladahealth.com/v1/tools/submit_query/schema

A real answer

{
 "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"
 }
}

What comes back

{
 "$defs": {
  "Quality": {
   "description": "Row-level quality signal. All flags precomputed at build time\n(stored on the gold mart) and passed through here.",
   "properties": {
    "is_outlier": {
     "default": false,
     "title": "Is Outlier",
     "type": "boolean"
    },
    "is_ghost_candidate": {
     "default": false,
     "title": "Is Ghost Candidate",
     "type": "boolean"
    },
    "n_similar_rates": {
     "default": 0,
     "title": "N Similar Rates",
     "type": "integer"
    },
    "confidence": {
     "default": 1,
     "title": "Confidence",
     "type": "number"
    }
   },
   "title": "Quality",
   "type": "object"
  },
  "Source": {
   "description": "Cell-level provenance. Every served value traces back here.\n\n`snapshot_id` is the Iceberg snapshot the tool read from. Two calls\nat the same snapshot MUST produce byte-identical responses —\nthat's the content-addressed caching guarantee.",
   "properties": {
    "table": {
     "title": "Table",
     "type": "string"
    },
    "rate_id": {
     "anyOf": [
      {
       "type": "string"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Rate Id"
    },
    "source_files": {
     "items": {
      "type": "string"
     },
     "title": "Source Files",
     "type": "array"
    },
    "snapshot_id": {
     "anyOf": [
      {
       "type": "integer"
      },
      {
       "type": "null"
      }
     ],
     "default": null,
     "title": "Snapshot Id"
    }
   },
   "required": [
    "table"
   ],
   "title": "Source",
   "type": "object"
  }
 },
 "properties": {
  "value": {
   "default": null,
   "title": "Value"
  },
  "unit": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Unit"
  },
  "vintage": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Vintage"
  },
  "source": {
   "$ref": "#/$defs/Source"
  },
  "methodology": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Methodology"
  },
  "quality": {
   "$ref": "#/$defs/Quality"
  },
  "invariants_applied": {
   "items": {
    "type": "string"
   },
   "title": "Invariants Applied",
   "type": "array"
  },
  "caveats": {
   "items": {
    "type": "string"
   },
   "title": "Caveats",
   "type": "array"
  },
  "response_hash": {
   "default": "",
   "title": "Response Hash",
   "type": "string"
  },
  "semantic_version": {
   "default": 1,
   "title": "Semantic Version",
   "type": "integer"
  },
  "tool_version": {
   "default": "unknown",
   "title": "Tool Version",
   "type": "string"
  },
  "explanation": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Explanation"
  },
  "status": {
   "default": "complete",
   "title": "Status",
   "type": "string"
  },
  "refusal": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Refusal"
  },
  "failure": {
   "anyOf": [
    {
     "additionalProperties": true,
     "type": "object"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "Failure"
  },
  "as_of": {
   "anyOf": [
    {
     "type": "string"
    },
    {
     "type": "null"
    }
   ],
   "default": null,
   "title": "As Of"
  },
  "freshness_state": {
   "default": "unknown",
   "title": "Freshness State",
   "type": "string"
  }
 },
 "title": "AsyncJobResponse",
 "type": "object"
}

Sources

Known limits (0)