> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iqrush.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Check query budget options

> Find candidate query counts for a proposed set of measurement dimensions.

Find candidate query counts for a proposed set of measurement dimensions.

**MCP tool:** `valid_query_budgets`. **Operation:** planning calculation. Uses the authorized connection; no project or content changes are made by this tool.

## Parameters

| Name | Type | Required | Default | Meaning and accepted values |
| - | - | - | - | - |
| `facets` | object\[] | Yes | `Required` | Array of objects with facet\_name and a nonempty options array describing the proposed dimensions. |
| `n_min` | integer | No | `1` | Lower bound on candidate queries per topic returned by the planning tool. |
| `n_max` | integer | No | `500` | Upper bound on candidate queries per topic returned by the planning tool. |

## Example call

Replace ID placeholders and example selections with values from your account. This is the `params` object for MCP `tools/call`.

```json theme={null}
{
  "name": "valid_query_budgets",
  "arguments": {
    "facets": [
      {
        "facet_name": "intent",
        "options": [
          "informational",
          "commercial"
        ]
      }
    ],
    "n_min": 10,
    "n_max": 30
  }
}
```

## Read the response

Read `candidates` and each candidate’s `n_queries`. Other returned planning fields are not needed for a customer-facing report.

### Fields to use

These selected fields explain the example and the result to preserve. Field presence depends on the response; this is not a complete response schema.

| Field | Meaning and use |
| - | - |
| `candidates[].n_queries` | Candidate query count per topic for the supplied facets. This is planning guidance, not a guarantee of statistical convergence. |

## Response example

Selected fields from an observed IQRush Dev response. Lists are shortened and project/run IDs are placeholders. Omitted fields remain available in the actual response.

```json theme={null}
{
  "candidates": [
    {
      "n_queries": 10
    }
  ]
}
```

Read the actual returned scope, counts, and interval levels before interpreting these fields.

## Important behavior

This is a planning helper. It does not create queries, price a run, start a measurement, or guarantee convergence. At least one facet must have nonempty options.

Check tool and payload errors before using the result. [Response handling](/developers/guides/09-responses-and-metrics) explains estimates and empty results; [errors and recovery](/developers/guides/13-errors) covers invalid requests and temporary failures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.