Queue

For requests that take longer than a few seconds, typical in AI applications, we’ve developed a queue system. This system offers you fine-grained control to manage traffic surges, cancel requests if needed, and monitor your request’s status in the queue. It also eliminates the need for handling long-running HTTP requests.

​

Queue Endpoints

You can access all queue features through endpoints added to your function URL using the queue subdomain. The available endpoints are:

For example, to submit a request using curl and add it to the queue:

curl -X POST \
  https://api.sunra.ai/queue/black-forest-labs/flux-1.1-pro/text-to-image \
  -H "Authorization: Key $SUNRA_KEY" \
  -d '{"prompt": "A Studio Ghibli-inspired seaside town with colorful houses, laundry flapping, and cats sleeping on windowsills."}'

Here’s a sample response including the request_id:

{
  "request_id": "pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_vXW7VwPN2MbTwT8bzpWrYU5Y/cancel"
}

The payload includes the request_id and provides URLs for checking status, canceling, or retrieving the response, streamlining your workflow without additional endpoint development.

​

Request Status

To monitor the progress of your request, use the provided endpoint with your unique request ID. This allows you to track the status, queue position, or retrieve the response once it’s ready.

​

Endpoint Usage

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status

​

Example Response

When your request is in the queue, you’ll receive a response like this:

{
  "status": "IN_QUEUE",
  "metrics": {},
  "queue_position": 0,
  "response_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf",
  "status_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/status",
  "cancel_url": "https://api.sunra.ai/v1/queue/requests/pd_hvTNHJPSZj4KgtzytfTGsySf/cancel"
}

​

Possible Statuses

Your request can be in one of three states:

• IN_QUEUE: Indicates the request is waiting to be processed.

  • queue_position: Shows your place in the queue.
  • response_url: URL for retrieving the response once processing completes.

• IN_PROGRESS: The request is currently being processed.

  • logs: Detailed logs (if enabled) showing processing steps.
  • response_url: Where the final response will be available.

• COMPLETED: Processing has finished.

  • logs: Logs detailing the entire process.
  • response_url: Direct link to your completed response.

​

Enabling Logs

Logs provide insights into request processing. They are disabled by default but can be enabled with a query parameter:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status?logs=1

Each log entry includes:

• message: Description of the event.
• level: Severity (e.g., INFO, ERROR).
• source: Origin of the log.
• timestamp: Time the log was generated.

​

Real-Time Monitoring

For continuous updates, use the streaming endpoint:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/status/stream

This provides real-time status updates in text/event-stream format until the request is completed.

​

Cancelling Requests

If your request is still queued, you can cancel it with:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}/cancel

​

Retrieving Responses

Once your request is COMPLETED, retrieve the response using:

curl -X GET https://api.sunra.ai/v1/queue/requests/{request_id}

This endpoint also provides logs for review.

​

Simplified Integration with Sunra Client

The Sunra client automates status tracking, simplifying app development with Sunra functions.