Sign in
Projects

List deployments across a user's projects

Changed on

Lists Function and Frontend deployment attempts across every project the user owns, newest first. Pass project_id to narrow the feed to a single project.

Scope is project ownership (projects.user_id). owner_id names whose deployments to return, not who started them — the actor is initiated_by_user_id, which this endpoint does not filter on.

With a user token the scope is always the authenticated user: owner_id may be omitted, or set to that same user, but naming anyone else is refused with 403. Service callers on the management API must pass it, since they have no authenticated user.

The owner is not checked for existence: an id with no projects returns an empty page rather than 404. Unlike /users/{id}/usage, this endpoint is polled to detect an event, so a caller needs 404 to keep meaning "this route is not served here" — which is how a consumer notices it is running against an older release. A mistyped owner therefore reads as "nothing deployed"; callers that need to tell those apart should verify the user through GET /users/{id} first.

Ordering is selectable. The default is the feed order — most recent attempt first. completed_at.asc orders by completion, oldest first, and considers only attempts that finished; combined with limit=1 and a status filter it answers "when did this user first succeed" in one bounded query.

Both pagination modes are supported, selected exactly as /projects/{id}/deployments selects them: cursor/ending_before (or a limit with no page) uses keyset pagination; otherwise page/limit offset pagination. page with a cursor, and cursor with ending_before, are rejected.

A cursor is bound to every filter and to order, so changing any of them mid-pagination rejects the cursor rather than silently skipping or repeating rows. The keyset position is (created_at, id) for created_at.desc and (completed_at, id) for completed_at.asc.

get/deployments

Request

  • Base URL: https://api.volcano.dev
  • URL: https://api.volcano.dev/deployments
  • Auth: HTTP bearer

Query parameters

pageinteger

Page number (1-indexed) for offset pagination. Declares no schema default so the request validator does not inject one: handlers that omit page see it unset (nil) and default to 1 in code, while cursor-first endpoints (e.g. the project deployments feed) can detect its absence to stay in keyset/search mode. Supplying page selects offset pagination.

limitinteger

Number of items per page (max 100)

cursorstring

Opaque keyset pagination cursor from a previous response's next_cursor — pages forward. Mutually exclusive with page and ending_before; combining them returns 400. When supplied, the request's search and limit must match the values bound to the cursor or the request returns 400.

ending_beforestring

Opaque keyset pagination cursor from a previous response's prev_cursor — pages backward (the page immediately preceding this cursor). Mutually exclusive with page and cursor; combining them returns 400. search and limit must match the values bound to the cursor or the request returns 400.

offsetinteger

Bounded row offset past the keyset anchor named by cursor (forward) or ending_before (backward) — the hybrid jump. Seek to the anchor, then skip this many rows within. Used for numbered jump-to-page: from the current page, seek to its next/prev cursor and offset the remaining pages. Only honored on the cursor pagination path; ignored otherwise.

owner_idstring

The user who owns the projects whose deployments to return (projects.user_id). This is ownership, not the actor that started the deployment — see initiated_by_user_id for that. Not a UUID: platform user ids are opaque strings.

project_idstring uuid

Restrict the feed to a single project owned by the user.

created_afterstring date-time

Restrict results to attempts created at or after this timestamp.

resource_type'function' | 'frontend'

Restrict a deployment feed to a single resource type. Omit to return both Function and Frontend deployments.

status'queued' | 'provisioning' | 'active' | 'degraded' | 'failed' | 'superseded' | 'deleting' | 'deleted'

Restrict a deployment feed to attempts in one status.

operation'deploy' | 'redeploy' | 'update' | 'delete'

Restrict a deployment feed to one kind of operation.

order'created_at.desc' | 'completed_at.asc'

Sort key and direction. created_at.desc (default) is the feed order. completed_at.asc orders finished attempts by completion, oldest first, and excludes attempts that never completed.

Response

Successful response

pageinteger

Current page number (1-indexed). Offset pagination only — omitted in cursor mode, where position comes from the cursor and there is no page number to report. Required-and-1-indexed would otherwise force a 0 onto every cursor response.

limitinteger required

Number of items per page

totalinteger required

Total number of items across all pages

has_moreboolean required

Whether there are more pages available

nextstring

URL path to next page (offset pagination only; present if has_more is true)

next_cursorstring

Opaque cursor for the next page (cursor pagination only; present if has_more is true)

prev_cursorstring

Opaque cursor for the previous page (cursor pagination only; present when a previous page exists). Send as ending_before.

Changes

  • 23e7875e7c4cRevision changes
    • ●

      removed the optional property // from the response with the status

  • 3a6f365f3f35Revision changes
    • ▲

      the response's body type changed from no type to object for status

    • ▲

      the response's body type changed from no type to object for status

    • ▲

      the response's body type changed from no type to object for status

    • ▲

      the response's body type changed from no type to object for status

    • ▲

      the response's body type changed from no type to object for status

    • ○

      added the new optional query request parameter cursor

    • ○

      added the new optional query request parameter ending_before

    • ○

      added the new optional query request parameter limit

    • ○

      added the new optional query request parameter offset

    • ○

      added the new optional query request parameter operation

    • ○

      added the new optional query request parameter order

    • ○

      added the new optional query request parameter owner_id

    • ○

      added the new optional query request parameter page

    • ○

      added the new optional query request parameter resource_type

    • ○

      added the new optional query request parameter status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the optional property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status