# Projects and usage (/docs/api/projects-and-usage)



Projects group your sandboxes, artifacts, and previews inside an
organization, and the usage endpoint reports how much compute your
organization has consumed in the current billing period.

## List projects [#list-projects]

`GET /v1/projects`

Returns a [list](/docs/api/pagination-and-idempotency) of the projects your
API key can access. The response includes `hasMore`, which is always `false`
for projects today.

| Field       | Type   | Description                          |
| ----------- | ------ | ------------------------------------ |
| `id`        | string | Project ID, prefixed `prj_`          |
| `orgId`     | string | Owning organization, prefixed `org_` |
| `name`      | string | Project name                         |
| `createdAt` | string | ISO 8601 creation timestamp          |

```bash title="Terminal"
curl https://api.crownest.dev/v1/projects \
  -H "Authorization: Bearer $CROWNEST_API_KEY"
```

```json
{
  "data": [
    {
      "id": "prj_abc123",
      "orgId": "org_abc123",
      "name": "default",
      "createdAt": "2026-06-11T13:00:00.000Z"
    }
  ],
  "hasMore": false
}
```

Pass a project's `id` as `projectId` when you
[create a sandbox](/docs/api/sandboxes#create-a-sandbox) or filter a
sandbox list.

## Create a project [#create-a-project]

`POST /v1/projects` — requires an org-wide API key with scope
`project:create`. Project-restricted keys cannot create projects.

```bash title="Terminal"
curl -X POST https://api.crownest.dev/v1/projects \
  -H "Authorization: Bearer $CROWNEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Agent Workspace" }'
```

Returns `201` with the project:

```json
{
  "project": {
    "id": "prj_agent_workspace",
    "orgId": "org_abc123",
    "name": "Agent Workspace",
    "createdAt": "2026-06-13T10:00:00.000Z"
  }
}
```

## Get usage [#get-usage]

`GET /v1/usage` — requires scope `usage:read`.

Returns compute usage, spend metadata, and quota information for the
current billing period.

```bash title="Terminal"
curl https://api.crownest.dev/v1/usage \
  -H "Authorization: Bearer $CROWNEST_API_KEY"
```

```json
{
  "period": {
    "start": "2026-06-01T00:00:00.000Z",
    "end": "2026-07-01T00:00:00.000Z",
    "resetAt": "2026-07-01T00:00:00.000Z"
  },
  "pricingVersion": "<current pricing version>",
  "computeUnitSecondsPerCredit": 30000,
  "currencyPerCredit": 0.03333333333333333,
  "computeUnitSeconds": { "used": 18250 },
  "credits": { "used": 18.25, "remaining": 81.75 },
  "quotas": {}
}
```

Response fields:

| Field                         | Type    | Description                                                                                                                                                                                 |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `period.start`                | string  | ISO 8601 start of the current billing period                                                                                                                                                |
| `period.end`                  | string  | ISO 8601 end of the current billing period                                                                                                                                                  |
| `period.resetAt`              | string  | ISO 8601 time usage counters reset                                                                                                                                                          |
| `pricingVersion`              | string  | Pricing scheme the figures are computed under                                                                                                                                               |
| `computeUnitSecondsPerCredit` | integer | How many compute unit seconds one credit buys                                                                                                                                               |
| `currencyPerCredit`           | number  | Dollar value paired with the conversion rate for this pricing version                                                                                                                       |
| `computeUnitSeconds.used`     | number  | Compute unit seconds consumed this period                                                                                                                                                   |
| `credits.used`                | number  | Compatibility usage value computed by the server                                                                                                                                            |
| `credits.remaining`           | number  | Free credit remaining when your plan has a capped balance                                                                                                                                   |
| `quotas`                      | object  | Quota buckets keyed by quota name, such as `max_concurrent_sandboxes` and `max_active_previews_per_org`. Each carries a `limit`, plus `current` and `remaining` when the quota is org-wide. |

<Callout type="info" title="Note">
  Quota values vary by plan tier and are subject to change.
</Callout>

## Next steps [#next-steps]

* Watch for `quota_exceeded` responses in [Errors](/docs/api/errors).
* Restrict keys to specific projects in
  [Authentication](/docs/api/authentication).