Logs REST API

The Logs REST API allows you to retrieve and search through logs from your fal applications. This is essential for debugging, monitoring, and understanding your application’s behavior in production.

Endpoints Overview

Endpoint	Method	Description
`/logs/`	POST	List logs with filtering capabilities

Authentication

All requests require authentication using your fal API key:

Authorization: Key $FAL_KEY

List Logs

POST /logs/

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of logs to return (default: 100)
`since`	string	No	ISO 8601 timestamp - logs after this time
`until`	string	No	ISO 8601 timestamp - logs before this time
`app_id`	string	No	Filter by application ID
`revision`	string	No	Filter by application revision
`traceback`	boolean	No	Include traceback information (default: false)
`search`	string	No	Search term to filter log messages
`level`	string	No	Minimum log level (DEBUG, INFO, WARNING, ERROR)
`job_id`	string	No	Filter by job ID
`request_id`	string	No	Filter by request ID

Request Body

Parameter	Type	Required	Description
`extra_filters`	array[LabelFilter]	No	Additional label-based filters

LabelFilter Object

Field	Type	Required	Description
`key`	string	Yes	Label key to filter on
`value`	string	Yes	Label value to match

Example Request

curl -X POST "https://rest.alpha.fal.ai/logs/?limit=10&app_id=github_5367102-test-startup-timeout" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "extra_filters": [
      {
        "key": "fal_env",
        "value": "prod"
      }
    ]
  }'

Response Format

Returns an array of log entry objects:

[
  {
    "timestamp": "2025-09-19T12:16:10.599608",
    "level": "INFO",
    "message": "71 seconds of sleep remaining",
    "app": "github_5367102-test-startup-timeout",
    "revision": "e6a6cf77-e803-4435-a647-7d9100ef79d9",
    "labels": {
      "app": "github_5367102-test-startup-timeout",
      "app_id": "e6a6cf77-e803-4435-a647-7d9100ef79d9",
      "fal_env": "prod",
      "fal_job_id": "41512b2d-d821-4d62-a98b-9472c9d43941",
      "fal_multiplexing_app": "1",
      "fal_node_id": "116aaad5-1074-b94c-e056-2b4ed093464a",
      "fal_public_logs": "1",
      "fal_user_nickname": "efiop",
      "fal_worker_id": "fal-jobs/S/41512b2d-d821-4d62-a98b-9472c9d43941",
      "isolate_source": "USER",
      "level": "INFO",
      "logged_at": "2025-09-19T12:16:10.599608+00:00",
      "message": "71 seconds of sleep remaining",
      "source": "gateway"
    }
  },
  {
    "timestamp": "2025-09-19T12:16:09.599522",
    "level": "INFO",
    "message": "72 seconds of sleep remaining",
    "app": "github_5367102-test-startup-timeout",
    "revision": "e6a6cf77-e803-4435-a647-7d9100ef79d9",
    "labels": {
      "app": "github_5367102-test-startup-timeout",
      "app_id": "e6a6cf77-e803-4435-a647-7d9100ef79d9",
      "fal_env": "prod",
      "fal_job_id": "41512b2d-d821-4d62-a98b-9472c9d43941",
      "fal_multiplexing_app": "1",
      "fal_node_id": "116aaad5-1074-b94c-e056-2b4ed093464a",
      "fal_public_logs": "1",
      "fal_user_nickname": "efiop",
      "fal_worker_id": "fal-jobs/S/41512b2d-d821-4d62-a98b-9472c9d43941",
      "isolate_source": "USER",
      "level": "INFO",
      "logged_at": "2025-09-19T12:16:09.599522+00:00",
      "message": "72 seconds of sleep remaining",
      "source": "gateway"
    }
  }
]

Time-based Filtering

When using since and until parameters:

Use ISO 8601 format: 2024-01-15T10:30:00Z or 2024-01-15T10:30:00.123Z
Times are treated as exclusive bounds (logs after since, logs before until)
If no time range is specified, recent logs are returned
Consider timezone when specifying times

Example with Time Range

curl -X POST "https://rest.alpha.fal.ai/logs/?since=2024-01-15T09:00:00Z&until=2024-01-15T11:00:00Z&limit=100" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Searching Logs

Use the search parameter to find logs containing specific text:

curl -X POST "https://rest.alpha.fal.ai/logs/?search=model%20inference&limit=50" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Traceback Information

When traceback=true, error logs will include full Python tracebacks in the labels:

curl -X POST "https://rest.alpha.fal.ai/logs/?level=ERROR&traceback=true" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Error Responses

Standard HTTP error responses:

400 Bad Request

{
  "detail": "Duplicate label key found: environment"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["query", "since"],
      "msg": "invalid datetime format",
      "type": "value_error"
    }
  ]
}