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 the following endpoints:
EndpointMethodDescription
api.sunra.ai/v1/queue/{model-id}POSTAdds a request to the queue
api.sunra.ai/v1/queue/requests/{request_id}/statusGETRetrieves the status of a request
api.sunra.ai/v1/queue/requests/{request_id}/status/streamGETStreams the status until completion
api.sunra.ai/v1/queue/requests/{request_id}GETFetches the response of a request
api.sunra.ai/v1/queue/requests/{request_id}/cancelPUTCancels a request
For example, to submit a request using curl and add it to the queue: 
curl -X POST \
  https://api.sunra.ai/v1/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 PUT 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.

​
Rate Limits

To ensure fair usage and system stability, our API endpoints are subject to the following rate limits:
Endpoint TypeRate LimitBurst Limit
Submit to Queue10 requests/second100 requests/minute
All Other Endpoints100 requests/second1,800 requests/minute
If you exceed these limits, you will receive a 403 Forbidden response. We recommend implementing a retry mechanism with exponential backoff to handle these cases.