# The workspace

> The API operations about the workspace, each with its input, its output and an example.

The operations about the workspace. Each one is a `POST` with a JSON object as its body: [Making a request](/docs/api#start) has the rules they share.

## Workspace details

`POST /api/v1/workspace.get` · Read

The workspace the token belongs to: its id, name, time zone and the period a report covers when range is left out. Takes no input: a token belongs to exactly one workspace and cannot name another. Use it to learn which days workspace.summary counts (they are days in this time zone) and which period a report without a range covers. For the sites of the workspace call sites.list, and for the plan's allowance usage.get. Keeps working while the workspace is locked.

Needs a token with the Read permission. Keeps answering while the dashboards of the workspace are locked.

### Input

No fields. Send an empty object, or no body.

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | always | The id of the workspace the token belongs to. |
| `name` | string | always | The name of the workspace. |
| `timezone` | string | always | The workspace's time zone, an IANA name such as Europe/Berlin. workspace.summary counts its days in this zone, and a new site starts with it. |
| `defaultRange` | "today" \| "yesterday" \| "30m" \| "12h" \| "24h" \| "week" \| "7d" \| "30d" \| "60d" \| "90d" \| "mtd" \| "ytd" \| "12mo" \| "all" \| "custom" | always | The period a report covers when range is left out. |
| `isDemo` | boolean | always | True only for the seeded demo workspace. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/workspace.get \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**CLI**

```bash
clearsaga workspace get --input '{}'
```

**MCP**

```text
Tool: workspace_get
Arguments: {}
```

Run `clearsaga help workspace get` for one flag per field.

## Visitors online now

`POST /api/v1/workspace.live` · Read

How many visitors are on each site of the workspace right now (a hit in the last two minutes), and their sum. Takes no input. A site that could not be asked within a few seconds is left out of the list and of the total, so a missing site does not mean zero. For everything else that is happening on one site call realtime.snapshot. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

### Input

No fields. Send an empty object, or no body.

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `sites` | array of object | always | Visitors online per site right now: visitors with a hit in the last two minutes. A site that could not be asked in time is left out. |
| `total` | number | always | The sum of online over the listed sites. |
| `serverNow` | number | always | The clock of the answer, milliseconds since 1970 UTC. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/workspace.live \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**CLI**

```bash
clearsaga workspace live --input '{}'
```

**MCP**

```text
Tool: workspace_live
Arguments: {}
```

Run `clearsaga help workspace live` for one flag per field.

## All sites summary

`POST /api/v1/workspace.summary` · Read

Every site of the workspace with its visitors, page views, revenue and visitors online for one period, ranked by visitors, and one roll-up that adds the sites up. Use it to compare sites or to answer a question about the whole account in one call. It takes a range and a comparison like the site reports, resolved in the workspace's time zone (not each site's), and no filters and no siteId. Visitors in the roll-up are a plain sum, so a person who visits two sites counts twice. Money is never converted: the roll-up shows the currency with the most orders and leaves the others out. A site that could not be asked within three seconds carries error true and is left out of the roll-up, which then says partial true. billing is always null for a token; call usage.get for the allowance. Nothing pages. Answers 402 workspace_locked while the workspace's dashboards are locked.

Needs a token with the Read permission. Answers 402 while the dashboards of the workspace are locked.

### Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `range` | "today" \| "yesterday" \| "30m" \| "12h" \| "24h" \| "week" \| "7d" \| "30d" \| "60d" \| "90d" \| "mtd" \| "ytd" \| "12mo" \| "all" \| "custom" | optional | The period to report on: one of today, yesterday, 30m, 12h, 24h, week, 7d, 30d, 60d, 90d, mtd, ytd, 12mo, all. Left out, the workspace's default range is used (30d unless it was changed). For exact dates send from and to and leave range out (custom is accepted with them and means the same). A preset together with dates answers 400. |
| `from` | string | optional | First day of a custom period, YYYY-MM-DD in the site's time zone. Send it together with to: one without the other answers 400, and so does a day that does not exist or a from after to. A day after today is read as today; window in the answer shows the period that was used. |
| `to` | string | optional | Last day of a custom period, inclusive, YYYY-MM-DD in the site's time zone. Send it together with from. |
| `compare` | "prev" \| "week" \| "month" \| "quarter" \| "year" \| "custom" \| "off" | optional | What the period is compared with: prev (the period just before, the default), week, month, quarter or year earlier, custom (cfrom and cto are then required), or off for no comparison. The range all never has a comparison. |
| `cfrom` | string | optional | First day of a custom comparison period, YYYY-MM-DD. Required with compare set to custom, where a day that does not exist or a cfrom after cto answers 400. |
| `cto` | string | optional | Last day of a custom comparison period, inclusive, YYYY-MM-DD. Required with compare set to custom. |

### Output

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `workspace` | object | always | The workspace: id, name, time zone (the days of the period are days in this zone) and the period used when range is left out. |
| `state` | "onboarding" \| "waiting" \| "normal" \| "viewer" \| "viewer_empty" \| "locked" | always | normal: the numbers are there. onboarding: the workspace has no site yet. waiting: its one site has not recorded a hit. The other values are for people in the dashboard and never reach a token. |
| `sites` | array of object | always | One row per site, most visitors first: id (the siteId site operations take), name, domain, firstEventAt (the first recorded hit in milliseconds since 1970 UTC, or null), online (visitors in the last two minutes), visitors and views of the period, visitorsDelta (the change of visitors against the comparison period as a fraction, null when there is nothing to compare with), revenue as { minor, currency } in minor units (cents) or null, and spark, up to 30 visitor counts across the period, oldest first. error is true for a site that could not be asked in time: its numbers are zeros and it is left out of the roll-up. |
| `rollup` | object \| null | always | All sites added up: visitors, visits and views (a person who visits two sites counts twice), bounceRate (a fraction from 0 to 1) and sessionTimeSec (seconds), both over visits that viewed a page (pvVisits, bounces and durationSumSec are their raw parts), revenue in the currency with the most orders (other currencies are left out, never converted) and orders in it. previous holds the same traffic numbers for the comparison period, or is null without one. partial is true when a site could not be asked and is missing from the sums. Null when the workspace has no numbers to show. |
| `billing` | null | always | Always null for a token. Call usage.get for the plan's allowance and what was used. |

### Example

**curl**

```bash
curl -s -X POST https://clearsaga.com/api/v1/workspace.summary \
  -H "Authorization: Bearer $CLEARSAGA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**CLI**

```bash
clearsaga workspace summary --input '{}'
```

**MCP**

```text
Tool: workspace_summary
Arguments: {}
```

Run `clearsaga help workspace summary` for one flag per field.