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

# List Sessions

> Retrieve all sessions for a workspace, along with aggregate stats.

## Authentication

Requires an [API key](/authentication).

## Query parameters

<ParamField query="organizationId" type="string">
  The ID of the workspace to list sessions for. Optional when using an API key (resolved automatically).
</ParamField>

## Response

<ResponseField name="sessions" type="array">
  Array of session objects (without full message history).

  <Expandable title="Session fields">
    <ResponseField name="id" type="string">Unique session identifier.</ResponseField>
    <ResponseField name="title" type="string">Session title (auto-generated or user-provided).</ResponseField>
    <ResponseField name="status" type="string">One of `active`, `completed`, or `failed`.</ResponseField>
    <ResponseField name="createdAt" type="datetime">When the session was created.</ResponseField>
    <ResponseField name="updatedAt" type="datetime">When the session was last updated.</ResponseField>
    <ResponseField name="model" type="string">The Claude model used.</ResponseField>

    <ResponseField name="author" type="object">
      The user who created the session.

      <Expandable title="Author">
        <ResponseField name="id" type="string">User ID.</ResponseField>
        <ResponseField name="name" type="string">Display name.</ResponseField>
        <ResponseField name="imageUrl" type="string">Avatar URL.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Repository and PR context.

      <Expandable title="Metadata">
        <ResponseField name="repository" type="string">Repository name (e.g., `owner/repo`).</ResponseField>
        <ResponseField name="branch" type="string">Working branch name.</ResponseField>
        <ResponseField name="prNumber" type="number">Pull request number.</ResponseField>
        <ResponseField name="prUrl" type="string">Pull request URL.</ResponseField>
        <ResponseField name="prStatus" type="string">One of `draft`, `open`, `merged`, `closed`.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="messageCount" type="number">Total number of messages in the session.</ResponseField>
    <ResponseField name="firstMessagePreview" type="string">Preview of the first message.</ResponseField>
    <ResponseField name="lastMessagePreview" type="string">Preview of the most recent message.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="stats" type="object">
  Aggregate statistics for the workspace.

  <Expandable title="Stats fields">
    <ResponseField name="mergesPastWeek" type="number">PRs merged from sessions in the last 7 days.</ResponseField>
    <ResponseField name="authorsPastWeek" type="number">Unique users who created sessions in the last 7 days.</ResponseField>
    <ResponseField name="humansPastWeek" type="number">Unique users active in the last 7 days.</ResponseField>
    <ResponseField name="humansPromptingNow" type="number">Users with active sessions right now.</ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://magnet.run/api/sessions" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://magnet.run/api/sessions', {
    headers: { 'x-api-key': 'YOUR_API_KEY' },
  });
  const { sessions, stats } = await response.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "sessions": [
    {
      "id": "cm3abc123def",
      "title": "Add input validation to signup form",
      "status": "completed",
      "createdAt": "2026-02-10T14:30:00.000Z",
      "updatedAt": "2026-02-10T14:45:00.000Z",
      "model": "claude-opus-4-6",
      "author": {
        "id": "user_123",
        "name": "Alice Chen"
      },
      "metadata": {
        "repository": "acme/web-app",
        "branch": "agent/add-signup-validation",
        "prNumber": 42,
        "prUrl": "https://github.com/acme/web-app/pull/42",
        "prStatus": "open"
      },
      "messageCount": 12,
      "firstMessagePreview": "Add input validation to the signup form...",
      "lastMessagePreview": "I've opened PR #42 with the changes..."
    }
  ],
  "stats": {
    "mergesPastWeek": 8,
    "authorsPastWeek": 3,
    "humansPastWeek": 5,
    "humansPromptingNow": 1
  }
}
```

## Errors

| Status | Description                          |
| ------ | ------------------------------------ |
| `401`  | Invalid or missing authentication    |
| `403`  | No access to the specified workspace |
| `500`  | Server error                         |