> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Operation activity API
> Read canonical current operations and paginated history without invoking an agent.
**Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.
## Goal
Integrate the version 1 read contract while preserving identity, access checks and source availability.
## Prerequisites
* An authenticated session or API token with the existing route permissions.
* A backend release that includes operation activity. No dedicated SDK wrapper or new CLI command is introduced by this phase.
## Workflow
GET the operation-activity collection for the selected resource.
Render current separately from history.items and deduplicate by id.
Refresh current state using the same IDs; follow an opaque history.next\_cursor only when history is complete.
GET an exact activity ID when inspecting a retained record or following an authorized parent reference.
## Read routes
All paths below are relative to `/api/v1`. Append `/{activityID}` to any collection for an exact read. Use the database route that matches its ownership context.
```text theme={null}
GET /projects/{projectID}/operation-activity
GET /applications/{appID}/operation-activity
GET /databases/{databaseID}/operation-activity
GET /projects/{projectID}/databases/{databaseID}/operation-activity
GET /agents/objectives/{objectiveID}/operation-activity
```
## Collection response
The normal StackShift response envelope contains `data.contract_version: 1`, `scope`, `observed_at`, `current`, `current_complete`, `history`, `availability` and `unresolved_references`.
* `id` is `source_kind:source_record_UUID`. Retain it across polling, reconnection and navigation. Build and deployment attempt IDs are distinct.
* Each item includes resource/environment references, operation title/type, normalized status, original source.status, terminal evidence, current step, initiator, channel, executor, available timestamps, parents, related\_resources, tasks and authorized read links.
* Normalized states are queued, running, waiting, completed, failed, cancelled, rolled\_back or unknown. Unknown terminal evidence is null; never convert it into success.
* An environment marked resource\_current describes the resource now, not a proven historical environment. Absent timestamps remain null.
* `history` contains items, limit, complete, has\_more and next\_cursor. Current records are returned separately on each page.
## Pagination and exact inspection
Collections accept `limit` from 1 to 100, default 25, and an opaque `cursor`. History is ordered by creation time descending, then canonical ID descending. Preserve fractional timestamp precision when ordering client-side. The cursor is bound to the viewer and selected resource; do not edit it or reuse it in another scope.
A cursor bounds history creation time, not operation state or future access. Current operations can finish between reads. Refreshes can move records between current and history. Reauthorize retained records through exact reads when refreshing a previously loaded history window.
Percent-encode the activity ID once in the path, for example `build%3A50000000-0000-4000-8000-000000000001`. Exact reads accept no pagination query. Existing activity, release, event and log routes remain compatible.
```bash theme={null}
# Set these for an environment where the activity release is available.
curl --get "$STACKSHIFT_API_BASE/api/v1/projects/$PROJECT_ID/operation-activity" \
-H "Authorization: Bearer $STACKSHIFT_API_KEY" \
--data-urlencode "limit=25"
# For the next page, also pass --data-urlencode "cursor=$NEXT_CURSOR".
```
## Incomplete sources and errors
* `availability.sources` identifies each source, its role, and available, unavailable or not\_applicable state. Inspect availability even after HTTP 200.
* An unavailable operation source sets current\_complete and history.complete false. History has\_more and next\_cursor are null, preventing false empty history or unsafe advancement.
* Unavailable relationship or task enrichment can make availability.complete false while operation history remains complete. Do not infer that missing relationships never existed.
* If every applicable operation source fails, the collection returns HTTP 503 with shaped partial data. A current-source limit is reported explicitly instead of silently hiding truncation.
* Invalid query parameters, cursors or malformed activity IDs return 400. Missing or inaccessible resources/records return 404; authentication failures return 401 and existing token-scope restrictions can return 403. Authority/source infrastructure failures return 503.
## Permissions and private tasks
The selected resource and every returned child resource are independently authorized. Application ownership does not grant access to a restricted service or database. Objective activity requires independent task access; resource access alone does not expose private tasks.
Responses contain safe operational facts, not conversation text, prompts, secrets, raw controller payloads or billing details. These GET routes do not reconcile controllers, run a model or consume AI credits. Use the returned authorized links for detailed readers; do not manufacture routes from display labels.
## Expected result
Consumers show current state, stable history and incomplete-source feedback without executing work.
## Related guides
Follow builds, deployments, releases and database operations from the resource you are working on.
Read safe resource-scoped agent actions, approval capabilities and recorded authorization evidence.
Call an existing customer API path with bounded inputs, safe retries, downloads, and path restrictions.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.