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.

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

API key must be prefixed 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

Show child attributes

⌘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"
  }
}