> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withwhile.com/llms.txt
> Use this file to discover all available pages before exploring further.

# whileai

> The platform client: sign in, push traces, read the account.

The platform client: sign in, push traces, read the account.

12 public names. `import whileai`, then `whileai.name`.

| Name                                            | What it does                                                                                                                  |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [`LoginError`](#loginerror)                     | Unspecified run-time error.                                                                                                   |
| [`WhileIngestError`](#whileingesterror)         | Raised when the gate rejects a trace batch.                                                                                   |
| [`ZeroProofIngestError`](#zeroproofingesterror) | Raised when the gate rejects a trace batch.                                                                                   |
| [`account`](#account)                           | Tier, limits and today's usage for the key in use (`GET /me`).                                                                |
| [`ingest_traces`](#ingest_traces)               | Push a local OTLP batch file end to end and return `\{datasetId, dataset, rows\}`.                                            |
| [`list_traces`](#list_traces)                   | What this key's account has ingested: one entry per dataset name per day, with row counts and sizes, plus the account totals. |
| [`login`](#login)                               | Run the device login.                                                                                                         |
| [`logout`](#logout)                             | Delete the saved credentials.                                                                                                 |
| [`otel_env`](#otel_env)                         | Environment for an OpenTelemetry OTLP/HTTP exporter.                                                                          |
| [`resolve_api_key`](#resolve_api_key)           | `explicit` > `WHILEAI_API_KEY` > the saved credentials file.                                                                  |
| [`send_traces`](#send_traces)                   | POST one OTLP/HTTP JSON batch (raw or gzipped) and return the 202 body.                                                       |
| [`signup`](#signup)                             | Create an account for `email` and save its API key.                                                                           |

## auth

Sign in or sign up from a terminal or a coding agent.

### LoginError

Unspecified run-time error.

### account

```python theme={null}
account(api_key: str | None = None) -> dict
```

Tier, limits and today's usage for the key in use (`GET /me`).

`tier` is `"trial"` for an account made by `signup` that has not
signed in yet; `trial["lift"]` says how to lift it.

### login

```python theme={null}
login(
    name: str | None = None,
    wait: bool = True,
    timeout: float | None = None,
    open_browser: bool = True,
    out: Callable[[str], None] | None = None,
) -> str | None
```

Run the device login. Returns the API key, or `None` if still pending.

`wait=False` prints the link and returns at once; run again to finish.
`timeout` caps the wait in seconds (default: until the code expires).

### logout

```python theme={null}
logout() -> bool
```

Delete the saved credentials. Returns whether anything was removed.

### resolve\_api\_key

```python theme={null}
resolve_api_key(explicit: str | None = None) -> str | None
```

`explicit` > `WHILEAI_API_KEY` > the saved credentials file.

### signup

```python theme={null}
signup(
    email: str,
    name: str | None = None,
    out: Callable[[str], None] | None = None,
) -> str
```

Create an account for `email` and save its API key. Returns the key.

No browser and no password: the person opens the dashboard later by
signing in with an email code. Raises `LoginError` if the address
already has an account (run `login` instead).

## ingest

OTLP trace ingest for the While token gate.

### WhileIngestError

Raised when the gate rejects a trace batch.

### ZeroProofIngestError

Raised when the gate rejects a trace batch.

### ingest\_traces

```python theme={null}
ingest_traces(
    api_key: str,
    file: str,
    dataset: str | None = None,
    base_url: str | None = None,
) -> dict
```

Push a local OTLP batch file end to end and return `\{datasetId, dataset,
rows\}`.

`dataset` overrides the dataset name by setting the dataset resource
attribute on every resourceSpan, which requires reading the batch; leave
it unset to send the bytes untouched.

### list\_traces

```python theme={null}
list_traces(
    api_key: str | None = None,
    base_url: str | None = None,
    timeout: int = 30,
) -> dict
```

What this key's account has ingested: one entry per dataset name per day,
with row counts and sizes, plus the account totals.

for t in list\_traces()\["traces"]:
print(t\["name"], t\["rows"], t\["sizeBytes"])

`api_key` resolves like every other platform call: the argument, then
`WHILEAI_API_KEY`, then the key `whileai login` saved.

### otel\_env

```python theme={null}
otel_env(
    api_key: str,
    dataset: str = 'traces',
    base_url: str | None = None,
) -> dict[str, str]
```

Environment for an OpenTelemetry OTLP/HTTP exporter.

The exporter sends the batch body itself and forwards
`OTEL_EXPORTER_OTLP_HEADERS` as request headers, so the key reaches the
gate. `http/json` is required: the gate parses the OTLP JSON wire format
and answers protobuf batches with a 415.

### send\_traces

```python theme={null}
send_traces(
    api_key: str,
    body: bytes,
    base_url: str | None = None,
    timeout: int = 60,
) -> dict
```

POST one OTLP/HTTP JSON batch (raw or gzipped) and return the 202 body.