# List a server's running intervals Returns the periods in which the server was running, each with why it stopped, and the period running now. It feeds the uptime timeline of a server's detail page. A server counts as running from when it starts after being created, or when a resume finishes, until a park finishes, a delete starts, access is revoked, or a lifecycle step fails. While a park is in progress the server is still running (and billed); a park that does not finish leaves the period unbroken. The periods come from the server's lifecycle log, the same one [List a server's event history](/docs/api-reference/forge-compute/list-host-events) reads, and their seconds are the uptime [Get a server's daily cost and uptime](/docs/api-reference/forge-compute/get-host-usage) reports. A server is visible to the person who created it and to members with `manage_forge`; anyone else is told it does not exist. Requires a bearer token (or API key) whose principal holds the `use_forge` capability in the acting organization. It works while Forge cloud compute is switched off. #### Path Parameters **`host_id`** string required The server's id: the `fchost_` id returned in `id`, or the UUID sent when the server was created (any letter case, with or without hyphens). #### Query Parameters **`from`** string optional First day of the period, inclusive, as `YYYY-MM-DD` (UTC). Defaults to the first day of `to`'s month; with neither `from` nor `to`, the period is the current calendar month (UTC). **`to`** string optional Last day of the period, inclusive, as `YYYY-MM-DD` (UTC). Defaults to the last day of `from`'s month. The period is at most 93 days, both ends counted. **`organization_id`** string optional The organization the server belongs to: send its `organization.id` (from [List your servers in every organization](/docs/api-reference/forge-compute/list-my-hosts)). Defaults to your current organization, where a server of another organization is not found. You must be an active member of it, or the request is refused with `403 ORGANIZATION_ACCESS_DENIED`. #### Headers **`X-Organization-Id`** string optional The same as `organization_id`, as a header. When both are sent, the query parameter wins. ## Returns - **`host_id`** string — the server's `fchost_` id. - **`current`** object or `null` — the period running now, `{started_at}`; `null` while the server is not running (for example while it is parked). - **`intervals`** array — every running period that overlaps the requested days, oldest first. Periods are not cut at the edges of the requested days: one that started before `from` keeps its real `started_at`. The period running now, if any, is last. Each has: - **`started_at`** string — when the server started running (UTC). - **`ended_at`** string or `null` — when it stopped running (UTC); `null` while it still runs. - **`ended_by`** string or `null` — why it stopped: `park` (a park finished: the server is saved and not running), `delete` (a delete started), `stop` (access was revoked and the server removed at once), `failure` (a lifecycle step failed). `null` while it still runs. Every timestamp is ISO 8601 in UTC with a `Z` suffix. ```json { "host_id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90", "current": {"started_at": "2026-10-02T07:12:00Z"}, "intervals": [ {"started_at": "2026-09-30T22:00:00Z", "ended_at": "2026-10-01T03:00:00Z", "ended_by": "park"}, {"started_at": "2026-10-02T07:12:00Z", "ended_at": null, "ended_by": null} ] } ``` ## Errors | Status | Code | When | | --- | --- | --- | | 401 | `AUTHENTICATION_REQUIRED` | No valid credential. | | 403 | `ORGANIZATION_ACCESS_DENIED` | `organization_id` or `X-Organization-Id` names an organization you are not an active member of. | | 403 | `INSUFFICIENT_PERMISSIONS` | The caller does not hold `use_forge` in the acting organization. | | 404 | `FORGE_COMPUTE_HOST_NOT_FOUND` | No server with this id in the acting organization, or it was created by someone else and the caller does not hold `manage_forge`. | | 422 | `INVALID_DATE_RANGE` | `to` is before `from`. | | 422 | `DATE_RANGE_TOO_LARGE` | The period is longer than 93 days. | | 422 | `VALIDATION_ERROR` | `from` or `to` is not a `YYYY-MM-DD` date. | | 422 | `INVALID_ID_FORMAT` | `host_id` is neither a UUID nor `fchost_<32 hex>`. | ```bash cURL curl "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90/intervals?from=2026-10-01&to=2026-10-31" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ```python Python SDK # pip install aitronos-sdk # # The Python SDK does not expose a typed `forge_compute` namespace yet, so call # the endpoint directly with the same credential you would pass to `Aitronos(...)` # — an API key or a bearer token, both sent as `Authorization: Bearer `. import httpx API_KEY = "your-api-key" url = "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90/intervals" body = httpx.get(url, headers={"Authorization": f"Bearer {API_KEY}"}).json() for interval in body["intervals"]: print(interval["started_at"], "->", interval["ended_at"] or "now", interval["ended_by"]) ``` ```python Python import os import requests token = os.environ["AITRONOS_TOKEN"] body = requests.get( "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90/intervals", headers={"Authorization": f"Bearer {token}"}, ).json() print("running since", body["current"]["started_at"] if body["current"] else "not running") ``` ```javascript JavaScript const response = await fetch( "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90/intervals", { headers: { Authorization: `Bearer ${process.env.AITRONOS_TOKEN}` } }, ); const { current, intervals } = await response.json(); console.log(current, intervals.filter((i) => i.ended_by === "park").length, "parks"); ``` **Response:** 200 OK ```json { "host_id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90", "current": {"started_at": "2026-10-02T07:12:00Z"}, "intervals": [ {"started_at": "2026-09-30T22:00:00Z", "ended_at": "2026-10-01T03:00:00Z", "ended_by": "park"}, {"started_at": "2026-10-02T07:12:00Z", "ended_at": null, "ended_by": null} ] } ``` 200 Parked ```json { "host_id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90", "current": null, "intervals": [ {"started_at": "2026-09-30T22:00:00Z", "ended_at": "2026-10-01T03:00:00Z", "ended_by": "park"} ] } ``` 422 Invalid range ```json { "success": false, "error": { "code": "INVALID_DATE_RANGE", "message": "The end date is before the start date. Choose an end date on or after the start date.", "system_message": "to (2026-10-04) is before from (2026-10-05)", "type": "validation_error", "status": 422, "details": {"from": "2026-10-05", "to": "2026-10-04"}, "trace_id": "3f1c9a52-7d4e-4b8a-9c21-6e0d5f7a8b34", "timestamp": "2026-10-02T12:30:00Z" } } ``` 404 Not Found ```json { "success": false, "error": { "code": "FORGE_COMPUTE_HOST_NOT_FOUND", "message": "This server could not be found. It may have been deleted.", "system_message": "Forge compute host not found", "type": "client_error", "status": 404, "details": {"resource": "forge_compute_host"}, "trace_id": "3f1c9a52-7d4e-4b8a-9c21-6e0d5f7a8b34", "timestamp": "2026-10-02T12:30:00Z" } } ``` ## Related Resources - [Forge cloud compute overview](/docs/api-reference/forge-compute/introduction) - [Get a server](/docs/api-reference/forge-compute/get-host) - [Get a server's daily cost and uptime](/docs/api-reference/forge-compute/get-host-usage) - [List a server's event history](/docs/api-reference/forge-compute/list-host-events) - [Park a server](/docs/api-reference/forge-compute/park-host) - [Resume a server](/docs/api-reference/forge-compute/resume-host)