FAfal
Models
Requests

List requests by endpoint(s)

Changed on

Lists requests for one or more endpoints (same endpoint_id style as usage/explore: comma-separated or repeated query params, up to 50 IDs).

Authentication: Requires API key (user or enterprise).

Filters:

  • Time range via start / end. If start is omitted, defaults to the last 24 hours — unless request_id is provided, in which case the default start bound is widened to 90 days.
  • Status (success, error, user_error)
  • Request ID
  • Pagination via cursor/limit (limit defaults to 50, max 100)

Sorting:

  • By end time (default) or duration

Expansions:

  • Include payloads by adding expand=payloads

Required permissions: models:requests:read. Key presets that include them: API, SERVERLESS, READONLY, FULL. See key permissions.

get/models/requests/by-endpoint

Request

  • Base URL
    https://api.fal.ai/v1
  • URL
    https://api.fal.ai/v1/models/requests/by-endpoint
  • Auth
    API key in header Authorization

Query parameters

limitinteger

Number of items to return per page (max 100)

Example:20
cursorstring

Pagination cursor encoding the page number

Example:Mg==
string required
OR
string[] required
string date-time
OR
string
string date-time
OR
string
status'success' | 'error' | 'user_error'

Filter by request status

Example:success
request_idstring uuid

Filter by specific request ID

Example:a1b2c3d4-e5f6-7890-abcd-ef1234567890
string
OR
string[]
sort_by'ended_at' | 'duration'

Sort results by end time or duration

Example:ended_at

Response

Requests listed successfully

next_cursorstring nullable required

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

has_moreboolean required

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

Example response

{
  "items": [
    {
      "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "endpoint_id": "fal-ai/flux/dev",
      "started_at": "2025-01-01T00:00:05Z",
      "sent_at": "2025-01-01T00:00:01Z",
      "ended_at": "2025-01-01T00:00:08Z",
      "status_code": 200,
      "duration": 7.8
    }
  ]
}

Changes

  • 479db2f9dcd6Revision changes
    • info

      the endpoint scheme security readonlyApiKey was added to the API

    • info

      the endpoint scheme security apiKey was removed from the API