Application Revisions

Returns the revision history for an application, newest first: every deployed version with its creation time, whether it is currently serving traffic, and a deployment status derived from recent deployment events.

Use cases:

Incident correlation: answer “did this regression start with a deploy?” by lining revision boundaries up against error/latency changes from the analytics endpoint
Rollback context: identify the previous known-good revision

status and deployed_by are derived from the last 30 days of deployment events; older revisions return null for both. message and annotations are the deploy-time metadata set via fal deploy --message/--annotation; both are null when the deploy did not set them.

Authentication: Required via API key. Only the app owner can query it.

Required permissions: serverless:apps:read. Key presets that include them: SERVERLESS, DEPLOY, READONLY, FULL. See key permissions.

GET

serverless

apps

{owner}

{name}

revisions

Application Revisions

curl --request GET \
  --url https://api.fal.ai/v1/serverless/apps/{owner}/{name}/revisions \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/serverless/apps/{owner}/{name}/revisions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "endpoint_id": "user_123/my-app",
  "revisions": [
    {
      "revision_id": "my-app-a1b2c3d4",
      "created_at": "2026-07-01T12:00:00Z",
      "is_current": true,
      "message": "a1b2c3d fix cold-start",
      "annotations": {
        "GIT_SHA": "a1b2c3d4"
      },
      "status": "deployed",
      "deployed_by": "user_123"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}

Authorizations

Authorization

string

header

required

Key on the READONLY preset, or any key whose permissions include the ones this API lists. Prefix it with "Key ", e.g. Authorization: Key YOUR_API_KEY

Path Parameters

owner

string

required

Username of the app owner

Example:

"user_123"

name

string

required

Application name

Example:

"my-app"

Query Parameters

limit

integer

default:50

Maximum number of revisions to return per page (1-100)

Required range: 1 <= x <= 100

Example:

50

cursor

string

Pagination cursor from previous response

Example:

"Mg=="

Response

Successfully retrieved application revisions

Revision history for an application

next_cursor

string | null

required

Cursor for the next page of results, null if no more pages

has_more

boolean

required

Boolean indicating if more results are available (convenience field derived from next_cursor)

endpoint_id

string

required

Canonical endpoint identifier ('/')

Example:

"user_123/my-app"

revisions

object[]

required

Application revisions, newest first

Hide child attributes

revisions.revision_id

string

required

Unique revision identifier

Example:

"my-app-a1b2c3d4"

revisions.created_at

string

required

Revision creation timestamp (UTC ISO8601)

Example:

"2026-07-01T12:00:00Z"

revisions.is_current

boolean

required

Whether this revision is the one currently serving traffic

Example:

true

revisions.message

string | null

required

Freeform message attached to this revision at deploy time (fal deploy --message). Null when the deploy did not set one.

Example:

"a1b2c3d fix cold-start"

revisions.annotations

object | null

required

Custom key/value annotations attached to this revision at deploy time (fal deploy --annotation KEY=VALUE). Null when the deploy did not set any.

Hide child attributes

revisions.annotations.{key}

string

Example:

{ "GIT_SHA": "a1b2c3d4" }

revisions.status

enum<string> | null

required

Deployment status derived from recent deployment events. Null when no deployment events are available for this revision (e.g. revisions older than the event retention window).

Available options:

deployed,

failed,

deploying

Example:

"deployed"

revisions.deployed_by

string | null

required

Nickname or display name of the user who deployed this revision, when known from recent deployment events

Example:

"user_123"

⌘I

Application Revisions

curl --request GET \
  --url https://api.fal.ai/v1/serverless/apps/{owner}/{name}/revisions \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.fal.ai/v1/serverless/apps/{owner}/{name}/revisions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "endpoint_id": "user_123/my-app",
  "revisions": [
    {
      "revision_id": "my-app-a1b2c3d4",
      "created_at": "2026-07-01T12:00:00Z",
      "is_current": true,
      "message": "a1b2c3d fix cold-start",
      "annotations": {
        "GIT_SHA": "a1b2c3d4"
      },
      "status": "deployed",
      "deployed_by": "user_123"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

{
  "error": {
    "type": "validation_error",
    "message": "Invalid request parameters"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Authentication required"
  }
}

{
  "error": {
    "type": "authorization_error",
    "message": "Access denied"
  }
}

{
  "error": {
    "type": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded"
  }
}

{
  "error": {
    "type": "server_error",
    "message": "An unexpected error occurred"
  }
}