Polling is an alternative result delivery method for AI Tools. 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
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.
sellershorts