Core concepts
Outcomes
Budget a unit of work, not a request, when one job is several calls.
A spend cap on a key limits a period. An outcome limits a *job*: one support reply, one document summarised, one agent run. however many calls that takes. It is the right ceiling when the thing you sell is a result rather than a token.
Define an outcome
seams outcomes add support-reply --name "Support reply" --limit 0.05
# OUTCOME DISPLAY NAME SPEND LIMIT USD RUNS SPENT USD
# support-reply Support reply 0.05 4812 18.40import { Seams } from "@ourseams/sdk"
const seams = new Seams({ apiKey: process.env.SEAMS_API_KEY! })
await seams.outcomes.add("support-reply", {
displayName: "Support reply",
ceilingMicros: "50000",
})
await seams.outcomes.show("support-reply")import os
from seams import Seams
seams = Seams(api_key=os.environ["SEAMS_API_KEY"])
seams.outcomes.add(
"support-reply",
display_name="Support reply",
ceiling_micros="50000",
)
seams.outcomes.show("support-reply")Attach a run to a call
Put the outcome on the request body. Same outcome_id across several calls is one run; a new id starts another.
curl https://<app>.gw.ourseams.com/v1/chat/completions \
-H "Authorization: Bearer ak_acme_…" \
-H "Content-Type: application/json" \
-d '{
"model": "acme/smart",
"messages": [{ "role": "user", "content": "Draft the reply" }],
"seams": {
"outcome": "support-reply",
"outcome_id": "ticket_8842"
}
}'Read runs and archive
seams outcomes runs --outcome support-reply
seams outcomes rm support-reply --yesawait seams.outcomes.runs("support-reply")
await seams.outcomes.rm("support-reply")seams.outcomes.runs("support-reply")
seams.outcomes.rm("support-reply")| Status | Means |
|---|---|
running | Calls are still being attributed to this run |
done | The job finished inside its ceiling |
capped | The ceiling was reached; further calls in this run are refused |
failed | The job stopped for a reason that was not money |
How it relates to the other ceilings
Three limits can apply to one call, and the tightest wins. None of them replaces the others: a balance is what a customer has, a cap is how fast they may spend it, and an outcome is how much one job may cost.
| Limit | Scope | Set on |
|---|---|---|
| Available balance | Everything that end user does | The balance |
| Spend cap | A period, per key | keys.cap |
| Bundle spend limit | A period, per end user | bundles.edit |
| Outcome ceiling | One run | outcomes.add |
outcomes.rm archives. Runs already recorded keep pointing at the outcome that produced them, so the history of what a job used to cost stays readable.