Skip to main content

​
What can you do with it?

Polling allows you to create long-running monitoring jobs that wait for external services to complete. This is perfect for tracking job statuses, waiting for processing to finish, handling asynchronous workflows, and integrating with services that require polling for results like video processing, data analysis, or web crawling. The service automatically handles retries, timeouts, and triggers callbacks when operations complete.

​
How to use it?

​
Basic Command Structure

/polling [pollUrl] [callbackUrl] [expectedResultPattern] [pollTime] [pollFrequency]

​
Parameters

Required:
  • pollUrl - URL to poll for results (e.g., “https://api.example.com/job/status”)
  • pollUrlToken - Authentication token for the polling URL
  • callbackUrl - URL to call when polling succeeds (e.g., “https://your-app.com/callback”)
  • callbackUrlToken - Authentication token for the callback URL
  • expectedResultPattern - Pattern to match for success with type and pattern
  • callbackPayload - Data to send to callback URL (supports a results templates)
  • pollTime - Total time to poll (1m-12h, e.g., “5m”, “2h”)
  • pollFrequency - How often to poll (5s, 10s, 20s, 30s, 1m, 3m, 5m)
Optional:
  • None

​
Response Format

The command returns: 
{
  "message": "Polling started successfully",
  "jobId": "poll_1234567890_abc123",
  "estimatedDuration": "5m",
  "frequency": "30s",
  "maxAttempts": 10
}

​
Examples

​
Basic Usage

/polling
pollUrl: https://api.example.com/job/status
pollUrlToken: your-polling-token
callbackUrl: https://your-app.com/callback
callbackUrlToken: your-callback-token
expectedResultPattern: {"type": "path", "pattern": "result.output.text"}
callbackPayload: {"message": "Job completed", "data": "{{results.result.output.text}}"}
pollTime: 5m
pollFrequency: 30s
Polls a job status endpoint every 30 seconds for up to 5 minutes until result.output.text exists.

​
Website Crawling

/polling
pollUrl: https://api.firecrawl.dev/v1/crawl/123-456-789
pollUrlToken: your-firecrawl-token
callbackUrl: https://your-app.com/crawl-complete
callbackUrlToken: your-callback-token
expectedResultPattern: {"type": "path", "pattern": "status"}
callbackPayload: {"crawlId": "{{results.id}}", "status": "{{results.status}}", "pages": "{{results.completed}}/{{results.total}}", "message": "Crawl completed"}
pollTime: 15m
pollFrequency: 30s
Monitors a Firecrawl website crawling job and sends detailed results when complete.

​
Video Processing

/polling
pollUrl: https://video-api.com/jobs/vid-456
pollUrlToken: your-video-token
callbackUrl: https://your-app.com/video-processed
callbackUrlToken: your-callback-token
expectedResultPattern: {"type": "stringMatch", "pattern": "processing complete"}
callbackPayload: {"videoId": "vid-456", "message": "Video processing finished", "result": "{{results}}"}
pollTime: 30m
pollFrequency: 1m
Waits for video processing to complete by checking for “processing complete” string in response.

​
Notes

Pattern Types:
  • path - Checks if a JSON path exists (e.g., “result.status”)
  • stringMatch - Checks if response contains specific text
Template Variables:
  • Use {{results}} in callback payload to inject polling results
  • Use {{results.path.to.data}} to inject specific data from results
Time Formats:
  • Poll Time: 1m to 12h (e.g., “5m”, “2h”, “30m”)
  • Poll Frequency: 5s, 10s, 20s, 30s, 1m, 3m, 5m
Error Handling:
  • Automatically retries on network errors
  • Stops on HTTP 4xx errors
  • Sends error callback on timeout or failure