Quickstart · Trace

This page takes an account with a Trace login to a working model call. It assumes Python 3.10 or newer and nothing else.

The pages that follow are reference, not tutorial. Curriculum lessons link here for the exact behaviour of a method; they teach the ideas themselves.

Install#

pip install trace-edu-sdk

The package depends on httpx and nothing else. It installs a library called trace_sdk and a command called trace.

trace login

The command prints a short code and opens your browser. Sign in to Trace if you are not already, check that the code on the screen matches the one in your terminal, and approve. The terminal finishes on its own:

  Your login code:  Q4EB-FUD7
  Approve it at:    https://trace.edu/account/link?code=Q4EB-FUD7

Waiting for you to approve… (Ctrl-C to cancel)

Signed in. Key saved to /Users/you/.trace/credentials.json (readable only by you).
Try it:  trace credits

The key is written to ~/.trace/credentials.json with file mode 0600. Trace never stores your key in readable form — see Authentication.

Your first call#

from trace_sdk import Trace

client = Trace()

completion = client.chat.completions.create(
    messages=[{"role": "user", "content": "Say hello in three words."}],
)

print(completion.choices[0].message.content)

If that shape looks familiar, it should. It is OpenAI's.

The surface mirrors the OpenAI library#

The Trace SDK deliberately looks like the SDK most of the world already uses:

client.chat.completions.create(messages=[...])   # a completion
client.embeddings.create(input="some text")      # vectors
client.models.list()                             # the roster

Everything you learn here maps method-for-method onto OpenAI's own documentation, onto examples elsewhere on the internet, and onto whatever you use after Trace. What Trace changes is only what it has to: how you sign in, the child-protection pipeline, credits, and friendlier errors.

Trace adds one namespace OpenAI has no equivalent for:

client.credits.balance()      # 472.5
client.credits.usage(limit=10)

The shortcuts#

A few additions sit beside the mirrored surface. Each is optional and none replaces the OpenAI path.

completion.text             # choices[0].message.content, "" instead of None
completion.credits_spent    # usage.credits_spent

model= is one of them: leave it out and Trace uses the roster's default, so there is nothing to choose before your first working line.

completion = client.chat.completions.create(messages=[...])                    # roster default
completion = client.chat.completions.create(messages=[...], model="openai/gpt-5.6-luna")
client = Trace(model="openai/gpt-5.6-luna")                                    # every request

Check your balance#

print(client.credits.balance())

trace credits
trace credits --usage 10

Free accounts receive 2,000 credits ($2) each month, while Self-learner subscribers receive 5,000 credits ($5). One credit is $0.001 of upstream cost at the published rate, so a short question against the default model costs a small fraction of one credit. See Credits and limits.

Why the calls go through Trace#

Your key is a Trace key, not a provider key, and every request runs the same student-safety pipeline as an agent-builder run: a reviewed child-safe model roster, server-side redaction of personal information before anything leaves Trace, per-request token caps, and a credit ceiling. That is the reason the gateway exists rather than handing students raw provider keys. The full description is in Authentication.

Running against a local Trace#

If you are running Trace yourself with docker compose, point the SDK at it:

export TRACE_BASE_URL=http://localhost:8000
trace login

TRACE_BASE_URL accepts either the app origin (http://localhost:8000) or the full gateway URL (http://localhost:8000/api/sdk/v1). Both resolve to the same place.