Sign in
Models
Requests

Search Requests

Search, filter, and browse your request history. Supports three modes:

1. Semantic Search (query, image_url, or video_url parameter): Find visually or conceptually similar results using AI embeddings. Provide a text query for text-to-image search, an image URL for image-to-image similarity search, or a video URL for video-to-image similarity search.

2. Filtered Browse (no query, image_url, or video_url): Browse request history with hard filters. Returns results ordered by creation date (newest first).

3. Semantic + Filters (search params AND filter params): Combine semantic search with hard filters. Filters narrow the candidate set before ranking by similarity.

Filter Options:

  • endpoint_id: Filter by one or more fal endpoints (comma-separated or repeated, up to 50 IDs)
  • exclude_api_requests / only_api_requests: Filter by request source

Examples:

  • Semantic text search: ?query=sunset+landscape
  • Image similarity: ?image_url=https://...&min_similarity=0.5
  • Filtered search: ?query=portrait&endpoint_id=fal-ai/flux/dev
  • Browse across multiple endpoints: ?endpoint_id=fal-ai/flux/dev,fal-ai/flux/schnell
get/models/requests/search

Query parameters

limitinteger

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

Example:50

Maximum number of items to return. Actual maximum depends on query type and expansion parameters.

cursorstring

Pagination cursor from previous response. Encodes the page number.

Example:Mg==

Pagination cursor from previous response. Encodes the page number.

querystring

Text search query for semantic search. Mutually exclusive with image_url and video_url.

Example:sunset landscape

Text search query for semantic search. Mutually exclusive with image_url and video_url.

image_urlstring

Image URL for similarity search. Mutually exclusive with query and video_url.

Example:https://v3.fal.media/files/abc123/output.png

Image URL for similarity search. Mutually exclusive with query and video_url.

video_urlstring

Video URL for similarity search. Mutually exclusive with query and image_url.

Example:https://v3.fal.media/files/abc123/output.mp4

Video URL for similarity search. Mutually exclusive with query and image_url.

string
OR
string[]

Filter by one or more fal endpoints to scope request history. Accepts comma-separated or repeated values (1-50 IDs).

endpointstring

Deprecated: use endpoint_id. Single-endpoint filter retained for backward compatibility. If both are provided, endpoint_id wins.

Example:fal-ai/flux/dev

Deprecated: use endpoint_id. Single-endpoint filter retained for backward compatibility. If both are provided, endpoint_id wins.

exclude_api_requestsboolean

Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests.

Example:true

Exclude requests made via API keys (only show playground/UI requests). Mutually exclusive with only_api_requests.

only_api_requestsboolean

Only include requests made via API keys. Mutually exclusive with exclude_api_requests.

Example:true

Only include requests made via API keys. Mutually exclusive with exclude_api_requests.

min_similaritynumber nullable

Minimum similarity score (0-1) for semantic search results. Only applies when query or image_url is provided.

Example:0.3

Minimum similarity score (0-1) for semantic search results. Only applies when query or image_url is provided.

Response

Successfully retrieved request search results

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

{
  "results": [
    {
      "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,
      "similarity": 0.87
    }
  ]
}

Changes

No recorded changes to this endpoint across all 2 revisions of this API.