Run configuration
Choose the model, thinking level, tools and budget for a single run.
A run can override a few of the deployment's settings under config.configurable. The table below is the whole list: anything else is rejected with a 422, never silently ignored.
| Field | Type | Effect |
|---|---|---|
provider | string | the model provider for this run, overriding the agent's model_profile |
model | string | the model for this run, overriding the agent's model_profile |
thinking | "off", "low", "medium", "high", or a boolean | extended thinking, where the provider supports it. false means "off", true means "medium" |
connect | list of strings | which MCP servers to use. It can only narrow the deployment's set, never add to it |
budget | object | per-run limits. They can only lower the deployment's limits |
agent_id | string | run one of your agents. It must be published unless preview is set |
preview | boolean | also run drafts: the agent and every subagent and skill it uses. Needs X-User-Role admin or owner, otherwise 403 |
connection_context | object | Data Brain connection details for this run's queries, sealed into its tool calls and never shown to the model |
for chunk in client.runs.stream(
thread_id,
"agent_platform",
input={"messages": [{"role": "user", "content": text}]},
config={"configurable": {
"model": "gpt-5.4-mini",
"thinking": "high",
"budget": {"max_usd": 0.25},
}},
stream_mode=["messages-tuple"],
):
...Budget
Every key is optional. Each one is combined with the deployment's value by taking the smaller, so asking for more than the deployment allows changes nothing.
Prop
Type
warn_fraction, the point at which operators are alerted, is deployment-only. A value you send is ignored.
Reaching a limit doesn't produce an HTTP error. The run ends with an assistant message saying the conversation hit its size limit; see runs that succeed but say no.
What you can't set, and why
| Field | Why |
|---|---|
tenant_id, api_key, jwt_secret, postgres_url | identity and deployment settings. Sending one returns a 422 and is logged |
hitl | whether a tool needs approval is the operator's policy, not a per-call switch |
thread_id | comes from the URL. Create the thread first; in configurable it's removed |
recursion_limit | deployment-owned. On a run it's silently replaced; on crons.create or assistants.create it's a 422 |
Keys the platform adds itself (thread_id, run_id, user_id, graph_id, checkpoint_* and similar) are removed before checking, so echoing a payload back doesn't trip the check.
When a field is rejected
The run is never created. The response names every bad field:
{
"error": "validation_error",
"message": "unsupported configurable field(s): ['temprature']. Deployment-owned settings cannot be set per run.",
"details": null
}That's a bug in the code that builds the config, not something to show a user. The same check runs on crons.create and assistants.create, so a bad config can't be saved now and fail later on a schedule.