List requests by endpoint(s)

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

GET /models/requests/by-endpoint

List requests by endpoint(s)

cURL

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

import requests

url = "https://api.fal.ai/v1/models/requests/by-endpoint"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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

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

200

{
  "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,
      "json_input": {
        "prompt": "cat astronaut"
      },
      "json_output": {
        "status": "ok"
      }
    }
  ],
  "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

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 · string string[] · 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 · string<date-time> string

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 · string<date-time> string

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 · string string[]

Fields to expand in the response. Use payloads to include input and output payloads.

Example:

["payloads"]

sort_by · enum<string> · default: ended_at

Sort results by end time or duration

Available options: ended_at, duration

Example:

"ended_at"

Response

200

application/json

Requests listed successfully

Paginated list of 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

Show child attributes