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

# List areas

> The current catalog of areas defined for the workspace.

Returns the workspace's current areas, sorted by name, then ID. Deleted areas and past versions are excluded.

## Authorization

Requires workspace Read. Pages contain current, non-deleted area definitions, not repository activity or productivity metrics. Renames, creation and deletion between requests can cause omissions or repeats; this is not a snapshot export.

**Authorization** `string` *required*

`Bearer <key>`. See [Authentication](https://docs.macroscope.com/api#authentication).

## Path parameters

**workspaceType** `string` *required*

`GITHUB_ORGANIZATION` or `GITHUB_USER`.

**workspaceId** `string` *required*

Numeric GitHub ID of the organization or user.

## Query parameters

**pageSize** `integer` (default: 50)

Maximum areas per page, 1 to 200. `0` and values above 200 return 400. Can change between pages.

**pageToken** `string`

`nextPageToken` from the previous response for the same workspace. Omit for the first page. Tokens expire within 24 hours and can be invalidated sooner; on 400, restart without a token.

## Response

**areas** `object[]`

Areas sorted by name, then ID. Omitted when the catalog is empty, so an empty catalog returns `{}`.

**properties**

**id** `string`

Area ID. Stable across renames and description changes.

**name** `string`

Display name. Not unique.

**description** `string`

Area description. Empty when none was supplied.

**validFrom** `string`

Start of the current version (RFC 3339, UTC). Editing an area resets it, so this is not the creation time.

**nextPageToken** `string`

Pass as `pageToken` to fetch the next page. Omitted on the last page. Pages are live reads, so concurrent edits can cause repeats or omissions.

```bash cURL theme={null}
curl "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/areas?pageSize=50" \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY"
```

```python Python theme={null}
import os, requests

r = requests.get(
    "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/areas",
    headers={"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"},
    params={"pageSize": 50},
)
print(r.json())
```

```javascript JavaScript theme={null}
const res = await fetch(
  "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/areas?pageSize=50",
  { headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
```

```json 200 theme={null}
{
  "areas": [
    {
      "id": "3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b01",
      "name": "Payments",
      "description": "Checkout, invoicing, and payment processing.",
      "validFrom": "2026-08-01T00:00:00Z"
    },
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e04",
      "name": "Search",
      "description": "Indexing and query services.",
      "validFrom": "2026-09-10T00:00:00Z"
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjJ9"
}
```

```json 401 theme={null}
{ "code": 16, "message": "unauthenticated" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.