Models

Every run executes on a model. Set model on an agent (the default for all its runs) or on a single run. Omit it for the platform default: deepseek-v4-1-flash at high reasoning effort.

List models

client.models.list() returns every selectable model with USD prices per million tokens. It is the live source of truth: an id outside the list returns a 422 naming the valid choices, and new models become selectable with no SDK change (model is a plain string).

from m8tes import M8tes

client = M8tes()

for m in client.models.list().data:
    print(m.id, m.name, m.pricing.input_per_mtok, m.pricing.output_per_mtok)

Each entry:

Set the model

Prefer runnable rows when choosing an account-scoped pin. Setting a model this write's scope cannot fund returns 400 MODEL_NOT_RUNNABLE — the models list is account-scoped by default, so an end-user-scoped agent/task/run may still accept a row that is runnable: false on the list when that tenant's prepaid/gateway lane can fund it. Connect the matching provider (or pass the write's end-user scope into your own visibility check) when the list flag is false.

A per-run choice wins for that run only:

client.agents.create(name="support agent", instructions="...", model="sonnet", user_id="customer_42")
client.agents.update(agent_id, model="opus", user_id="customer_42")   # change it later
client.agents.update(agent_id, model=None, user_id="customer_42")     # back to the platform default

# per-run override, agent default untouched
client.runs.create(agent_id=bot.id, message="draft the weekly report", model="opus", user_id="customer_42")

Resolution precedence, most specific first: per-run model, then the task's model, then the agent's, then the platform default.

A task can override its agent's model, which is the tool for a mixed workload: pin one high-stakes recurring task to a stronger model while the agent's routine work stays on the default.

task = client.tasks.create(
    agent_id=bot.id,
    instructions="review the contract and flag risk",
    model="opus",           # this task only; the agent is untouched
    effort="max",
    user_id="customer_42",
)
client.tasks.update(task.id, model=None, user_id="customer_42")   # clear the pin, inherit the agent's again

effort follows the same cascade and the same null-clears-the-pin rule.

Use your own provider subscription

Use your own model subscription for personal runs without user_id.

Provider terms and limits apply. Production runs with user_id use the prepaid balance.

1. Connect in the dashboard

Open Account → Model providers, connect an external model provider, and continue on the provider's own sign-in page. Some providers show a one-time device code; others ask you to paste a code from the provider page. m8tes saves the encrypted connection automatically. You never download or upload a token file.

After Connect succeeds, choosing Make default sets that provider as your account default. Platform mates still following the default then run on your plan; Keep as default leaves the current default unchanged. Disconnect clears a matching preference. On Teams the account default is Auto (m8tes-funded); upgrading from Hobby or Individual clears a preferred external provider so Auto is selected. To switch back to Auto without disconnecting, call client.model_connections.clear_default() (DELETE /api/v2/model-connections/preferred-default).

Each connected provider also has its own Default model picker. Saving a model does not switch your preferred provider. Mates following Default use that provider's saved model when routed through the connection; an explicit mate or run model keeps precedence. The setting applies to new runs, not an already-running turn. End-user-scoped API agents do not inherit these personal account defaults.

Use client.model_connections.set_default_model("claude", model="sonnet") to save a choice, or pass model=None to reset it. The corresponding endpoint is PATCH /api/v2/model-connections/{provider}/default-model with {"model": "sonnet"} or {"model": null}. Models must be known and belong to that connected provider. Connection responses include the saved default_model (null when following the platform's provider default), the effective resolved_default_model, and provider_default_model: the model the provider runs when nothing is saved.

OpenAI device authorization is a Codex beta feature. If the provider page says it is disabled, enable device-code authorization in your ChatGPT account or workspace settings and try again.

2. Connect through the API or SDK

OpenAI and xAI use device codes. Show the URL and code, then poll until connected. This example handles expiry and timeout:

import time
from m8tes import M8tes

client = M8tes()
auth = client.model_connections.authorize("xai")
print("Open:", auth.authorization_url)
print("Enter code:", auth.user_code)

deadline = time.monotonic() + 600
while auth.status == "pending":
    if time.monotonic() >= deadline:
        raise TimeoutError("Connection timed out. Run this script again.")
    time.sleep(max(auth.interval_seconds, 1))
    auth = client.model_connections.authorization_status("xai", auth.state)

if auth.status != "connected":
    raise RuntimeError("Connection failed: " + auth.status)
print("Connected. Run the Grok example below.")

For OpenAI, replace both "xai" values with "openai" and use a GPT/Codex model.

from m8tes import M8tes

client = M8tes()
auth = client.model_connections.authorize("gemini")  # or client.model_connections.authorize("claude")
print("Open:", auth.authorization_url)
result = client.model_connections.complete_authorization(
    auth.provider, auth.state, code=input("Paste the provider code: ")
)
print(result.status)

Provider values are claude, openai, xai, and gemini. Pending sessions expire and are bound to the account that started them. List redacted connection status with GET /api/v2/model-connections; cancel a pending session with DELETE /api/v2/model-connections/{provider}/authorizations/{state}; disconnect with DELETE /api/v2/model-connections/{provider}.

3. Select a matching model

Set model="gpt-6.1-sol" for Codex, model="grok-4.7" for xAI, or model="gemini-3.6-flash" for Gemini. Omitting model does not mean xAI just because it is connected: an active provider preference wins first; eligible own-inference plans then follow connected-provider precedence; platform plans without a preference can still use the platform default (and platform credits). Only once xAI is the selected provider does the omitted-model default become that provider's default (grok-4.7). A run uses a subscription only when its model matches that provider; run.auth_method is "oauth_subscription" and run.auth_provider identifies "openai", "xai", "gemini", or "claude".

Credentials are account-level. They are never attached to a run carrying user_id, because that workload acts for an API end user rather than the credential owner. Disconnecting deletes m8tes' encrypted copy. Codex and Grok OAuth refreshes produced during a run are persisted back through an authenticated, run-scoped callback. Gemini tokens are refreshed at run start instead.

Reasoning effort

effort controls how hard the model reasons before acting: low | medium | high | xhigh | max. Higher effort means deeper reasoning and more tokens per run; lower is faster and cheaper. Omit it for the platform default: max on Claude models, high on all others.

Same shape as model: set it on the agent, override it per run, explicit null resets.

client.agents.create(name="intake bot", instructions="...", effort="low", user_id="customer_42")   # cheap, fast default
client.runs.create(agent_id=bot.id, message="untangle this billing bug", effort="max", user_id="customer_42")
client.agents.update(agent_id, effort=None, user_id="customer_42")   # back to the platform default

Precedence mirrors model: per-run effort, then the task's effort, then the agent's, then the platform default. Resumes and replies inherit the run's effort, so a conversation keeps the depth it started with.

Ceilings, not errors. xhigh and max are Claude-only tiers. Other models clamp a higher request down to high, never reject it, so an agent set to max stays valid when a run overrides the model. Each model's ceiling is max_effort in the catalog. An invalid tier returns a 422 naming the valid choices.

Zero data retention (ZDR)

zdr_supported=true means at least one provider for that model supports zero data retention. It does not mean every route is ZDR, and it does not mean ZDR is enabled for your account. Retention protection applies only when routing lands on a ZDR-capable host and ZDR is enabled on the key. zdr_providers names the capable hosts.

zdr_supported=false means we have no confirmed zero-data-retention host for that model. Either none exists, or the model is not in the synced provider catalog. Either way treat it as may-retain: those models stay selectable on the API, so check the flag before sending customer data, or filter with GET /api/v2/models?zdr=true.

See Data Retention for the account-level picture.

Next: Agents · Data Retention