Polling Delivery (Alternative Method)
Polling is an alternative result delivery method for AI Shorts. Instead of your automation POSTing results to our callback URL, we periodically check your status endpoint to retrieve results.
⚠️ When to use polling
Use polling only if your automation platform cannot POST results to our callback URL. Callback delivery is faster (instant) and more reliable than polling (15-minute intervals).
Callback vs Polling comparison
| Feature | Callback | Polling |
|---|
| Delivery speed | Instant | Every 15 minutes |
| Setup complexity | Medium (POST endpoint) | Low (GET endpoint) |
| Buyer experience | Best (fast delivery) | Slower |
| Recommended | ✅ Yes | Only if callback not possible |
How polling works
- Order starts – We send inputs to your webhook
- You process – Your automation works in the background
- We check status – Every 15 minutes, we call your polling endpoint
- You respond with status – Return "processing", "completed", or "failed"
- Order completes – When you return "completed" with results
Working with large files?
You can reuse the same prepare → PUT direct-upload flow described in Callback (Over 4.5 MB) and return the resulting object_key in your polling response.
System requirements
Two separate endpoints required
Polling requires two different webhook endpoints in your automation:
- Job Webhook (POST) – Receives the initial job request with inputs
- Status Endpoint (GET) – Returns current status when we poll
Both endpoints use the same authentication headers you configured in the Connect step.
Polling URL format
Your polling URL must be a GET endpoint that accepts an order ID in the URL path.
Requirements
- Protocol: HTTPS only (HTTP not allowed)
- Method: GET requests
- Placeholder: Must include
{order_id} in the URL - Authentication: Uses the same headers you configured in Connect step
URL examples
https://your-api.com/orders/{order_id}/statushttps://your-domain.com/api/check-status/{order_id}https://api.example.com/v1/jobs/{order_id}
Response formats
Still processing
{
"status": "processing",
"progress": "45%"
}
- status: Must be "processing"
- progress: Optional – percentage complete (e.g., "45%" or 0.45 or 45)
Completed with text result
{
"status": "completed",
"output_type": "text",
"result_text": "Your analysis results go here..."
}
Completed with file result
{
"status": "completed",
"output_type": "file",
"file_base64": "base64-encoded-file-content",
"filename": "report.pdf",
"mime_type": "application/pdf"
}
Completed with direct-upload file
{
"status": "completed",
"output_type": "video",
"files": [
{
"object_key": "orders/order-uuid/20241109-ab12cd-final-video.mp4",
"filename": "final-video.mp4",
"mime_type": "video/mp4"
}
]
}
Use this format after uploading large files through the prepare → PUT flow. Include the same object_key you received from the prepare endpoint.
Completed with URL result
{
"status": "completed",
"output_type": "url",
"result_url": "https://your-storage.com/path/to/result.pdf"
}
Failed
{
"status": "failed",
"error_message": "Unable to process the provided input"
}
Response field requirements
Status (required)
- Values: "processing", "completed", or "failed"
- Type: String
For completed status
- output_type: One of "text", "html", "json", "csv", "file", "url", "xlsx", "video"
- result_text: For text/html/json/csv content (max 10MB)
- result_url: HTTPS URL to hosted file (must be publicly accessible)
- file_base64: Base64-encoded file content (requires filename and mime_type)
- files: Array of outputs when referencing uploads via
object_key - filename: Name of the file (required with file_base64 or in files array)
- mime_type: MIME type of the file (required with file_base64 or in files array)
- object_key: Required inside
files entries when using direct upload
For failed status
- error_message: Human-readable explanation of what went wrong (max 1024 characters)
Polling frequency and timing
- Check interval: Every 15 minutes
- First check: 5 minutes after order starts
- Timeout: Your endpoint has 8 seconds to respond
- Retries: 1 retry on network failure
Polling lifecycle
What happens after you return status
- Status: "processing" – We continue checking every 15 minutes
- Status: "completed" – We stop polling, deliver results to buyer immediately
- Status: "failed" – We stop polling, notify buyer of failure
Automatic timeout protection
If your endpoint doesn't return "completed" or "failed" within the expected time, orders are automatically flagged:
| ETA Bucket | Timeout After |
|---|
| under_2_min | 10 minutes |
| under_1_hr | 90 minutes |
| within_24_hr | 24 hours |
When an order times out, polling stops and you'll receive a notification to investigate the issue.
File handling
Allowed file types (MIME types)
When returning files, only these MIME types are accepted:
- Documents: application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document (DOCX), application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (XLSX)
- Text: text/plain, text/html, text/csv, application/json
- Images: image/jpeg, image/jpg, image/png, image/gif, image/webp, image/svg+xml
- Video: video/mp4, video/quicktime, video/webm, video/x-msvideo
- Audio: audio/mpeg, audio/wav, audio/aac, audio/ogg
- Archives: application/zip, application/x-zip-compressed
File size limits
- Base64 encoded: Maximum 50MB (encoded string size)
- Actual file size: Approximately 37MB after decoding
- Recommendation: For files larger than 5MB, use
result_url instead of base64 encoding
Security considerations
- Authentication required: Use the same auth headers you configured in Connect step
- HTTPS only: HTTP endpoints are blocked for security
- Public endpoints not recommended: Always require authentication
- File URLs must be HTTPS: HTTP URLs in result_url will be rejected
- Rate limiting: Ensure your endpoint can handle checks every 15 minutes
Best practices
- Use callback if possible: Faster and more reliable for buyers
- Return accurate status: Don't keep returning "processing" if actually failed
- Include progress updates: Help buyers understand how long to wait
- Host large files: Use result_url instead of base64 for files over 5MB
- Set proper MIME types: Ensures correct file handling and display
- Keep responses small: Return only necessary data
- Cache status in database: Don't recompute on every poll - return stored status
Testing your polling endpoint
- Create test endpoint: Set up a GET endpoint with
{order_id} placeholder - Return "processing" initially: Test that we can reach your endpoint
- Add authentication: Verify your headers are checked
- Test completion: Return "completed" with sample results
- Test failure: Return "failed" with error message
- Check response time: Ensure endpoint responds within 8 seconds
✅ Pro tip
Store order status in your database and return it when we poll. Don't recalculate or reprocess on every poll request – just return the current status. This keeps your endpoint fast and reliable.
Common issues and solutions
Endpoint timing out
- Cause: Endpoint takes longer than 8 seconds to respond
- Solution: Return cached status immediately, don't perform computations during poll
Authentication failures
- Cause: Missing or invalid authentication headers
- Solution: Verify same headers from Connect step are validated on GET requests
Order ID not found
- Cause: Your system hasn't stored the order yet
- Solution: Ensure job webhook stores order_id before we start polling
💡 Remember
Polling is slower than callback delivery. Results are delivered every 15 minutes at best. Your endpoint must remain accessible throughout the entire processing time.