# Request to the agent backend (GPT / Flask): route token usage count

From: HeavyHaul Agent Workspace · 2026-10-01 · Requested by Nash.

## Why

On a trip created in HeavyHaul Agent, a route is sold, and its price depends on how well the route is known (`docs/TASKS-2026-10-01-ROUTE-PURCHASE-RULE.md`):

- the route token has been used on **3 or more permits** → **Express Route**
- on **2 or fewer** → **Extended Route**

Nash: "We need to check MongoDB… that's where we keep all the tokens for every single route." Workspace has no MongoDB connection and should not get one; it asks the backend. Today the backend returns the token but not how often it has been used, so Workspace falls back to counting permits in its own database, which holds only a handful and prices almost every route as Extended.

## One question to answer first

**Which number in MongoDB is "how many permits have used this route token"?** We understand from `WORKSPACE_PERMIT_PROCESSING.md` that:

- a Synchron catalog route has a numeric token and a `Frequency` field, which Workspace extraction deliberately does not increment;
- a new route gets a `workspace:<hash>` token in `workspace_routing_tokens`, and usage is recorded once per permit/file in `workspace_route_usage`.

Our assumption, to confirm or correct:

| Token | Count |
|---|---|
| numeric (Synchron catalog) | `Frequency` + the number of `workspace_route_usage` records for that token |
| `workspace:<hash>` | the number of `workspace_route_usage` records for that token |

The count must **include the permit being read now**: the first permit ever to produce a token has a count of 1.

## What we need

### 1. The count in the existing permit extraction response

`POST /api/workspace/extract/permit` → add one field to each `states_info[]` item:

```json
{
  "states_info": [{
    "state_name": "Texas",
    "route_token": "4411",
    "route_source": "synchron",
    "route_status": "ready",
    "route_usage_count": 7
  }]
}
```

`route_usage_count`: non-negative integer, counted after this permit's usage has been recorded. Omit the field (do not send 0) if it cannot be determined. Workspace stores it with the permit.

### 2. A lookup, so the price is current when the route is bought

```
POST /api/workspace/route-token-usage
Authorization: Bearer <existing Workspace credential>
Content-Type: application/json

{ "tokens": ["4411", "workspace:9f2c…"] }
```

```json
{ "usage": { "4411": 7, "workspace:9f2c…": 1 } }
```

- Up to 50 tokens per call. Unknown tokens are simply absent from `usage`.
- Read-only. It must never increment `Frequency` or write usage.
- Same authentication as the other `/api/workspace/*` calls; tell us if it needs a new scope.
- Workspace waits at most 4 seconds, caches an answer for 5 minutes for page loads, and always asks fresh at the moment of purchase.

## What Workspace already does (deployed with this request)

`src/lib/data/route-offers.ts` `resolveTokenUses`, in this order:

1. the live lookup above;
2. `route_usage_count` stored from the extraction response;
3. its own database count — temporary, removed once 1 and 2 are live.

Each offer records which source priced it (`uses_source`: `backend`, `reader`, `workspace_db`), so we can see on a trip whether MongoDB answered. No Workspace change is needed when the backend ships; both pieces are picked up automatically.

## Not requested

No billing, no writes to MongoDB, no change to matching, no change to Synchron's own flow.
