List requests by endpoint(s)

Lists requests for one or more endpoints owned by the authenticated user. Use repeated or comma-separated `endpoint_id` (same as other platform list APIs). A bare app id ('<owner>/<name>') automatically includes the app's registered route-level endpoints (e.g. '<owner>/<name>/turbo'); each returned row keeps the route-level `endpoint_id` it was recorded under. Pass a route-level id to filter to that route exactly. **Authentication:** Requires API key. **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 - Include per-request `billable_units` by adding expand=billing (endpoint owner only) **Required permissions:** `serverless:requests:read`. Key presets that include them: `API`, `SERVERLESS`, `READONLY`, `FULL`. See [key permissions](https://fal.ai/docs/documentation/model-apis/authentication/key-based#permissions).

GET

serverless

requests

by-endpoint

List requests by endpoint(s)

curl --request GET \
  --url https://api.fal.ai/v1/serverless/requests/by-endpoint \
  --header 'Authorization: <api-key>'

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

fetch('https://api.fal.ai/v1/serverless/requests/by-endpoint', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "endpoint_id": "fal-ai/flux/dev",
      "runner_id": "f1e2d3c4-b5a6-7890-dcba-0987654321fe",
      "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,
      "json_input": {
        "prompt": "cat astronaut"
      },
      "json_output": {
        "status": "ok"
      },
      "billable_units": 1.5
    }
  ],
  "next_cursor": "Mg==",
  "has_more": true
}

{
  "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

Query Parameters

limit

integer

default:50

Number of items to return per page (max 100)

Required range: 1 <= x <= 100

Example:

20

cursor

string

Pagination cursor encoding the page number

Example:

"Mg=="

endpoint_id

required

Filter by specific endpoint ID(s). Accepts 1-50 endpoint IDs. Supports comma-separated values: ?endpoint_id=model1,model2 or array syntax: ?endpoint_id=model1&endpoint_id=model2

Example:

["fal-ai/flux/dev"]

start

Start date in ISO8601 format (e.g., '2025-01-01T00:00:00Z' or '2025-01-01'). Defaults to 24 hours ago.

Example:

"2025-01-01T00:00:00Z"

end

End date in ISO8601 format, exclusive (e.g., '2025-02-01T00:00:00Z' or '2025-02-01'). Data up to but not including this timestamp is returned. Defaults to current time.

Example:

"2025-02-01T00:00:00Z"

status

enum<string>

Filter by request status

Available options:

success,

error,

user_error

Example:

"success"

request_id

string<uuid>

Filter by specific request ID

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

expand

Fields to expand in the response. Use payloads to include input and output payloads. Use billing to include billable_units per request; billing also requires the billing:usage:read permission.

Example:

["payloads", "billing"]

sort_by

enum<string>

default:ended_at

Sort results by end time or duration

Available options:

ended_at,

duration

Example:

"ended_at"

Response

Requests listed successfully

Paginated list of serverless requests for the specified endpoint

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)

items

object[]

required

List of requests matching the filter

Hide child attributes

items.request_id

string<uuid>

required

Unique identifier for the request

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

items.endpoint_id

string

required

Endpoint that was executed for this request

Example:

"fal-ai/flux/dev"

items.started_at

string<date-time>

required

Time when request processing started

Example:

"2025-01-01T00:00:05Z"

items.sent_at

string<date-time>

required

Time when request was sent to the backend

Example:

"2025-01-01T00:00:01Z"

items.runner_id

string<uuid> | null

required

Unique identifier for the runner execution instance. Null if no runner was assigned (e.g. the request failed before dispatch).

Example:

"f1e2d3c4-b5a6-7890-dcba-0987654321fe"

items.ended_at

string<date-time> | null

Time when request finished processing

Example:

"2025-01-01T00:00:08Z"

items.status_code

integer | null

HTTP status code returned by the request

Example:

200

items.duration

number | null

Total request duration in seconds

Example:

7.8

items.json_input

any

Input payload for the request

items.json_output

any

Output payload for the request

items.billable_units

number | null

Billable units for this request (only present when expand=billing). Null if a billing event has not yet been recorded for this request.

Example:

1.5

⌘I

List requests by endpoint(s)

curl --request GET \
  --url https://api.fal.ai/v1/serverless/requests/by-endpoint \
  --header 'Authorization: <api-key>'

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

fetch('https://api.fal.ai/v1/serverless/requests/by-endpoint', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "endpoint_id": "fal-ai/flux/dev",
      "runner_id": "f1e2d3c4-b5a6-7890-dcba-0987654321fe",
      "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,
      "json_input": {
        "prompt": "cat astronaut"
      },
      "json_output": {
        "status": "ok"
      },
      "billable_units": 1.5
    }
  ],
  "next_cursor": "Mg==",
  "has_more": true
}

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