# List your hosted diagrams

> Page: https://docs.plotwork.dev/api/get-user-diagrams. Index of every page: https://docs.plotwork.dev/llms.txt

The account's hosted diagrams, most recently published first and at most 200, with the account's plan, how many diagrams and bytes it holds in total, and the plan's limits.

`GET /user/diagrams`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | List your hosted diagrams. |
| What does it take? | Nothing. |
| What does it return? | Status 200 with a body of type [`HostedDiagramList`](https://docs.plotwork.dev/api/schemas.md#hosteddiagramlist). |
| What can go wrong? | `401` not signed in; `429` too many requests; `503` hosting is not set up on this server. Every failure uses the one error envelope. |

## What it does

The account's hosted diagrams, most recently published first and at most 200, with the account's plan, how many diagrams and bytes it holds in total, and the plan's limits.

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The diagrams and the usage. | [`HostedDiagramList`](https://docs.plotwork.dev/api/schemas.md#hosteddiagramlist) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Hosting is not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`HostedDiagramList`](https://docs.plotwork.dev/api/schemas.md#hosteddiagramlist).

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | `HostedDiagram[]` | yes | At most 200, newest published first. |
| `items[].id` | `string` | yes | The handle for managing the diagram (delete). It is not in the link. |
| `items[].url` | `string` | yes | The public address of the SVG. Anyone with the link can see it; the token in it cannot be guessed. |
| `items[].name` | `string \| null` | yes | The label given at publish, or null. |
| `items[].folder` | `string \| null` | yes | The folder it is filed in, such as `Payments/Checkout`, or null for the top level. |
| `items[].theme` | `"light" \| "dark" \| "auto"` | yes | The color scheme it was drawn in: light, dark, or auto. |
| `items[].bytes` | `integer` | yes | Size of the stored SVG in bytes. |
| `items[].createdAt` | `integer` | yes | When it was first published, in milliseconds since the epoch. |
| `items[].publishedAt` | `integer` | yes | When it was last published, in milliseconds since the epoch. Publishing the same diagram again moves it. |
| `items[].expiresAt` | `integer \| null` | yes | When it will be deleted, in milliseconds since the epoch, or null when the plan keeps diagrams until you delete them. |
| `items[].locked` | `boolean` | yes | True while the diagram is locked: it cannot be deleted, renamed or moved until you unlock it. A lock does not stop it expiring on a plan that expires diagrams. |
| `items[].lockedAt` | `integer \| null` | yes | When it was locked, in milliseconds since the epoch, or null when it is not locked. |
| `stableLinks` | `StableLink[]` | yes | Every stable link the account keeps, by alias, including any whose diagram is gone. |
| `stableLinks[].id` | `string` | yes | The handle for managing the stable link (delete). It is not in its address. |
| `stableLinks[].alias` | `string` | yes | The name you gave it. Only you see it. |
| `stableLinks[].url` | `string` | yes | The public address, on the CDN host. It shows the diagram the stable link points at now (cached for up to 60 seconds) and never changes. Anyone with it can see the picture. |
| `stableLinks[].diagramId` | `string \| null` | yes | The diagram it shows now, or null when that diagram was deleted or expired; the address then answers 404 until you point the link at a diagram again. |
| `stableLinks[].createdAt` | `integer` | yes | When it was made, in milliseconds since the epoch. |
| `stableLinks[].updatedAt` | `integer` | yes | When it was last pointed at a diagram, in milliseconds since the epoch. |
| `usage` | `HostingUsage` | yes |  |
| `usage.plan` | `"free" \| "pro"` | yes | The plan the account is on, which decides the limits. |
| `usage.count` | `integer` | yes | Hosted diagrams the account holds. This is the total, even when the list is shorter. minimum 0. |
| `usage.bytes` | `integer` | yes | Total size of the hosted diagrams in bytes. minimum 0. |
| `usage.stableLinks` | `integer` | yes | Stable links the account keeps. minimum 0. |
| `usage.limits` | `HostingPlanLimits` | yes |  |
| `usage.limits.dailyCalls` | `integer` | yes |  |
| `usage.limits.hostedDiagrams` | `integer` | yes |  |
| `usage.limits.hostedBytes` | `integer` | yes |  |
| `usage.limits.retentionDays` | `integer \| null` | yes | Days a diagram is kept after it was last published, or null to keep it until you delete it. |
| `usage.limits.maxDiagramBytes` | `integer` | yes |  |
| `usage.limits.stableLinks` | `integer` | yes | Stable links the account may keep at once. |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |