---
title: "TypeScript SDK · Ataris docs"
description: "The @ataris/sdk client for reading sessions and their events, and errors."
canonical: "https://ataris.dev/docs/reference/sdk"
last-updated: 2026-10-12
---
# TypeScript SDK

The @ataris/sdk client for reading sessions and their events, and errors.

`@ataris/sdk` is the TypeScript client for reading your traced sessions from the Ataris API: list them, look one up, page through its events, or follow it live. Runs are recorded by the [`ataris` CLI](/docs/guides/cli). The SDK has no runtime dependencies and runs on Node.js 18 or later, or any runtime with `fetch` and web streams.

```bash
npm install @ataris/sdk
```

## Ataris

```ts
import { Ataris } from "@ataris/sdk"

const ataris = new Ataris({ apiKey: process.env.ATARIS_API_KEY })
```

| Option | Description |
| --- | --- |
| `apiKey` | A workspace API key (`atk_…`). Defaults to the `ATARIS_API_KEY` environment variable. |
| `baseUrl` | Defaults to `https://api.ataris.dev`. |
| `fetch` | A custom `fetch`, for tests or proxies. Defaults to the global `fetch`. |

### ataris.sessions

| Method | Returns | Description |
| --- | --- | --- |
| `get(id)` | `Session` | A handle on an existing session. |
| `list({ tag?, state?, limit?, cursor? })` | `{ sessions, nextCursor }` | Newest first. `tag` keeps sessions carrying every tag you pass. `state: "active"` means not yet finished. Pass `nextCursor` back as `cursor`. |
| `events(id, { after?, limit? })` | `{ events, nextAfter, hasMore }` | One page of stored events. |

## Session

A handle on one session. `session.data` is the latest summary this handle has seen.

| Member | Description |
| --- | --- |
| `id` | The session id. |
| `data` | The latest `SessionSummary`. |
| `refresh()` | Re-read the summary from the API. |
| `wait({ timeoutMs?, pollMs?, signal? })` | Resolve with the final summary once the session ends. |
| `events({ after?, signal?, onSession?, maxRetries?, retryDelayMs? })` | Async iterable of trace events. See [Stream trace events](/docs/guides/stream-events). |

### SessionSummary

| Field | Description |
| --- | --- |
| `id` | Session id. |
| `tags` | The session's `key:value` tags. See [Tags and missions](/docs/concepts/agents). |
| `mission` | What the agent was asked to do. |
| `state`, `stateReason` | See [session states](/docs/concepts/sessions#session-states). |
| `command` | The command that ran. |
| `harness`, `models` | The harness and models detected in the run. |
| `eventCount`, `flaggedCount` | Events recorded, and how many were flagged. |
| `createdAt`, `startedAt`, `endedAt` | ISO timestamps. |
| `dashboardPath` | The session's path in the Ataris dashboard. |

## Errors

Every failure is an `AtarisError`:

| Field | Description |
| --- | --- |
| `status` | The HTTP status, or `0` when there was no response. |
| `type` | `unauthorized`, `invalid_request`, `not_found`, `conflict`, `rate_limited`, `internal`, `connection`, `timeout`, or `invalid_response`. |
| `message` | What went wrong. |
| `issues` | Validation details, as `{ path, message }`. |
| `retryAfterSeconds` | Set on `429` responses. |

```ts
import { isAtarisError } from "@ataris/sdk"

try {
  const session = await ataris.sessions.get(sessionId)
  console.log(session.data.state)
} catch (err) {
  if (isAtarisError(err) && err.status === 404) {
    // no such session in this workspace
  } else {
    throw err
  }
}
```