queue

API reference for @fal-ai/client queue

Classes & Interfaces

QueueClient

interface QueueClient

Represents a request queue with methods for submitting requests, checking their status, retrieving results, and subscribing to updates.

Methods

submit

submit(endpointId: Id, options: SubmitOptions<InputType<Id>>): Promise<InQueueQueueStatus>

Submits a request to the queue.

Parameter	Type	Description
endpointId	Id	- The ID of the function web endpoint.
options	SubmitOptions<InputType<Id>>	- Options to configure how the request is run.

Returns: Promise<InQueueQueueStatus>

status

status(endpointId: string, options: QueueStatusOptions): Promise<QueueStatus>

Retrieves the status of a specific request in the queue.

Parameter	Type	Description
endpointId	string	- The ID of the function web endpoint.
options	QueueStatusOptions	- Options to configure how the request is run.

Returns: Promise<QueueStatus>

streamStatus

streamStatus(endpointId: string, options: QueueStatusStreamOptions): Promise<FalStream<unknown, QueueStatus>>

Subscribes to updates for a specific request in the queue using HTTP streaming events.

Parameter	Type	Description
endpointId	string	- The ID of the function web endpoint.
options	QueueStatusStreamOptions	- Options to configure how the request is run and how updates are received.

Returns: Promise<FalStream<unknown, QueueStatus>>

subscribeToStatus

subscribeToStatus(endpointId: string, options: QueueStatusSubscriptionOptions): Promise<CompletedQueueStatus>

Subscribes to updates for a specific request in the queue using polling or streaming. See options.mode for more details.

Parameter	Type	Description
endpointId	string	- The ID of the function web endpoint.
options	QueueStatusSubscriptionOptions	- Options to configure how the request is run and how updates are received.

Returns: Promise<CompletedQueueStatus>

result

result(endpointId: Id, options: BaseQueueOptions): Promise<Result<OutputType<Id>>>

Retrieves the result of a specific request from the queue.

Parameter	Type	Description
endpointId	Id	- The ID of the function web endpoint.
options	BaseQueueOptions	- Options to configure how the request is run.

Returns: Promise<Result<OutputType<Id>>>

cancel

cancel(endpointId: string, options: BaseQueueOptions): Promise<void>

Cancels a request in the queue.

Parameter	Type	Description
endpointId	string	- The ID of the function web endpoint.
options	BaseQueueOptions	- Options to configure how the request is run and how updates are received.

Returns: Promise<void>

---

Types

QueuePriority

type QueuePriority = "low" | "normal"

QueueStatusSubscriptionOptions

type QueueStatusSubscriptionOptions = QueueStatusOptions &
  QueueModeOptions &
  Omit<QueueCommonSubscribeOptions, "onEnqueue" | "webhookUrl">

QueueSubscribeOptions

type QueueSubscribeOptions = QueueCommonSubscribeOptions &
  QueueModeOptions

Options for subscribing to the request queue.

SubmitOptions

type SubmitOptions = RunOptions<Input> & {
  /**
   * The URL to send a webhook notification to when the request is completed.
   * @see WebHookResponse
   */
  webhookUrl?: string;

  /**
   * The priority of the request. It defaults to `normal`.
   * This will be sent as the `x-fal-queue-priority` header.
   *
   * @see QueuePriority
   */
  priority?: QueuePriority;

  /**
   * A hint for the runner to use when processing the request.
   * This will be sent as the `x-fal-runner-hint` header.
   */
  hint?: string;

  /**
   * Server-side request timeout in seconds. Limits total time spent waiting
   * before processing starts (includes queue wait, retries, and routing).
   * Does not apply once the application begins processing.
   *
   * This will be sent as the `x-fal-request-timeout` header.
   */
  startTimeout?: number;

  /**
   * Additional HTTP headers to include in the submit request.
   *
   * Note: `priority`, `hint`, `startTimeout`, and `objectLifecycle` will override the following headers:
   *  - `x-fal-queue-priority`
   *  - `x-fal-runner-hint`
   *  - `x-fal-request-timeout`
   *  - `x-fal-object-lifecycle-preference`
   */
  headers?: Record<string, string>;
}

Options for submitting a request to the queue.

QueueStatusOptions

type QueueStatusOptions = BaseQueueOptions & {
  /**
   * If `true`, the response will include the logs for the request.
   * Defaults to `false`.
   */
  logs?: boolean;
}

QueueStatusStreamOptions

type QueueStatusStreamOptions = QueueStatusOptions & {
  /**
   * The connection mode to use for streaming updates. It defaults to `server`.
   * Set to `client` if your server proxy doesn't support streaming.
   */
  connectionMode?: StreamingConnectionMode;
}