Skip to main content
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>'
{
  "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
}

Documentation Index

Fetch the complete documentation index at: https://fal.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

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

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