Polling Delivery (Alternative Method)

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.

Callback vs Polling comparison

How polling works

1. Order starts – We send inputs to your webhook
2. You process – Your automation works in the background
3. We check status – Every 15 minutes, we call your polling endpoint
4. You respond with status – Return "processing", "completed", or "failed"
5. Order completes – When you return "completed" with results

System requirements

Two separate endpoints required

Polling requires two different webhook endpoints in your automation:

1. Job Webhook (POST) – Receives the initial job request with inputs
2. 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}/status
• https://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", "json", "csv", "file", "url", "xlsx", "video"
• result_text: For text/json/csv content (max 10MB)
• result_url: HTTPS URL to hosted file (must be publicly accessible, including HTML files)
• 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:

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

1. Create test endpoint: Set up a GET endpoint with {order_id} placeholder
2. Return "processing" initially: Test that we can reach your endpoint
3. Add authentication: Verify your headers are checked
4. Test completion: Return "completed" with sample results
5. Test failure: Return "failed" with error message
6. Check response time: Ensure endpoint responds within 8 seconds

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