Skip to main content

​
When to use polling

Polling is the simplest way to get execution results. Call GET /v1/executions/{id} in a loop until the status reaches a terminal state.
Polling is rate-limited and intended for testing, prototyping, and small-scale applications where you want to validate your idea quickly. For production applications at scale, use webhooks instead — they deliver results instantly with zero wasted API calls and no rate limit concerns.

​
Basic polling loop

import time
import requests

API_KEY = "sk_your_api_key_here"
EXECUTION_ID = "exec_a1b2c3d4-e5f6-7890-abcd-ef1234567890"

while True:
    response = requests.get(
        f"https://api.modelroute.ai/v1/executions/{EXECUTION_ID}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    execution = response.json()
    status = execution["status"]

    if status in ("COMPLETED", "FAILED", "CANCELLED", "EXPIRED"):
        break

    # Respect rate limits — check X-RateLimit-Remaining header
    time.sleep(2)

if status == "COMPLETED":
    # Fetch the result
    result = requests.get(
        f"https://api.modelroute.ai/v1/executions/{EXECUTION_ID}/result",
        headers={"Authorization": f"Bearer {API_KEY}"}
    ).json()
    print(result)
elif status == "FAILED":
    print(f"Error: {execution['error']['code']} — {execution['error']['message']}")

​
Rate limit headers

Every response includes rate limit information: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1710924600
If you hit the limit, you’ll receive a 429 Too Many Requests with a Retry-After header telling you how many seconds to wait.
Use caseIntervalNotes
Testing / dev2 secondsFine for a few concurrent executions
Small app (< 100 executions/day)3-5 secondsStay well within rate limits
Production (> 100 executions/day)Use webhooksPolling doesn’t scale — switch to webhooks

​
Fetching the result

Once status is COMPLETED, fetch the full result: 
curl -X GET https://api.modelroute.ai/v1/executions/{execution_id}/result \
  -H "Authorization: Bearer sk_your_api_key_here"

{
  "execution_id": "exec_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "output": {
    "images": [
      {
        "file_id": "file_f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "format": "png",
        "width": 1024,
        "height": 1024
      }
    ]
  },
  "usage": {
    "input_tokens": 12,
    "output_tokens": 0
  },
  "cost": "0.040",
  "latency_ms": 8420
}
Download any files using the file download flow.