TerraFlow Hosted preview

Synthetic data only · no uptime commitment · 10:00–22:00 IST (04:30–16:30 UTC)

Tour

The "Start here" panel, at the top of the console's Command center (the first screen after you sign in), walks through six steps and ticks each one when your workspace shows it happened. This page follows the same six steps, with the same numbers and names, for readers who would rather try them from their own code. Set up a client first, as in the integration guide, with your key in TERRAFLOW_API_KEY. The examples use the OpenAI Python SDK; the Anthropic SDK behaves the same on /v1/messages.

What ticks which step. The panel ticks a step from what the workspace records:

So the code on this page shows each step from your side, and your first call ticks step 6, Connect your own code, whichever step you are reading. To tick steps 1 to 5 as well, press their Run buttons on the panel.

Real-model steps cost a few cents of your workspace's allowance. Use only synthetic text, like the samples below.

1. Your first governed request

In the console, send the Playground's sample request (this ticks step 1). From your own code (this ticks step 6):

raw = client.chat.completions.with_raw_response.create(
    model="starter-assistant",
    messages=[{"role": "user", "content": "In two sentences, what does an AI control plane do?"}],
    extra_headers={"X-TerraFlow-Data-Class": "internal"},
)
print(raw.headers["x-terraflow-outcome"], raw.headers["x-terraflow-reason"])   # EXECUTED PERMITTED
print(raw.headers["x-terraflow-capability"], raw.headers["x-terraflow-cost-usd"])
print(raw.parse().choices[0].message.content)

What to look for: the model TerraFlow chose, and what it cost at list price. In the console, open the request in Routing Explorer to see the decision funnel: every model in the catalogue, and why each one was or was not eligible.

2. Blocked before it leaves

On the panel, Run: Blocked before it leaves ticks step 2. From your own code, two requests that never reach a provider:

# A confidential request, pinned to an external model, on the workload that keeps confidential data in
client.chat.completions.create(
    model="anthropic-opus",
    messages=[{"role": "user", "content": "Summarise this synthetic memo: Project Lark is on schedule."}],
    extra_headers={"X-TerraFlow-Workload": "starter-confidential", "X-TerraFlow-Data-Class": "confidential"},
)   # 403 EXTERNAL_EGRESS_NOT_ALLOWED

# A request carrying a published test card number
client.chat.completions.create(
    model="starter-assistant",
    messages=[{"role": "user", "content": "Synthetic test: refund card 4111 1111 1111 1111."}],
)   # 403 DATA_CLASS_NOT_PERMITTED

What to look for: both are refused with a 403 your SDK raises as a permission error. The second one was declared nothing at all: the scan found a card number, raised the request to restricted data, and the workload accepts only public and internal data. The evidence records what was detected (a count by type, never the number itself). Send the first request without model="anthropic-opus" and it is answered by the simulated private model instead.

3. Same question, no second bill

On the panel, Run: Same question, no second bill ticks step 3. From your own code, send the request from step 1 again, word for word.

What to look for: x-terraflow-reason: CACHE_HIT, x-terraflow-cache: hit, a cost of zero, and a savings header measured against the baseline model's estimated list-price cost for the same request. The answer came from your workspace's in-memory cache; no provider was called.

4. Evidence you can check

import httpx, os
request_id = raw.headers["x-terraflow-request-id"]
events = httpx.get(f"https://<your-workspace-host>/v1/requests/{request_id}/evidence",
                   headers={"Authorization": f"Bearer {os.environ['TERRAFLOW_API_KEY']}"}).json()
print([event["event_type"] for event in events["events"]])

What to look for: the decision, the execution and the cost, without the prompt or the answer. In the console's Evidence screen, run chain verification: it recomputes the hash chain and checks the signed checkpoints. On the panel, Run: Evidence you can check ticks step 4: it sends a request and then verifies the chain.

5. Spend stops where you set it

for attempt in range(3):
    try:
        client.with_options(max_retries=0).chat.completions.create(
            model="starter-budget", messages=[{"role": "user", "content": "Name three primary colours."}])
        print(attempt, "answered")
    except Exception as error:
        print(attempt, error)   # 429 BUDGET_EXHAUSTED

What to look for: starter-budget has an hourly budget big enough for one cheap call. In a fresh hour the first call is answered and the next is denied BUDGET_EXHAUSTED before any provider is called. The budget is per hour: if step 5 already ran this hour, from the panel or from your code, the hour's budget is spent, so every call is denied BUDGET_EXHAUSTED from the first one. That is the stop working, not a fault. The FinOps screen shows the spend against the budgets; the banner at the top of the console shows how much of your workspace's allowance is used. On the panel, Run: Spend stops where you set it ticks step 5 either way.

6. Connect your own code

Copy a snippet from the console's Connect panel, which already carries your workspace's host and your key's prefix, into your own project and send a request.

What to look for: your request in Routing Explorer, on the openai or anthropic channel, with the same decision, cost and evidence as every request above. The console ticks this step when it sees it, and keeps it ticked. If you sent any of the requests above from your own code, it is already ticked.

Next