Polling Command Guide - Pinkfish AI Generative Workflows

The /polling command enables you to create long-running polling jobs that wait for external services to complete and trigger callbacks. Perfect for:

Long-running async operations
External service monitoring
Webhook-style callbacks
Background job processing
Service completion tracking

Basic Usage

Use the command to set up polling operations:

/polling monitor Firecrawl job until completion then notify

/polling wait for video processing to finish then send results

/polling check API status every 30 seconds for 10 minutes

Key Features

Long-Running Operations

Configurable polling duration (1m-12h)
Flexible polling frequency
Automatic retry handling
Error recovery
Timeout management

Pattern Matching

JSON path matching
String content matching
Flexible success criteria
Custom validation
Result extraction

Callback System

Webhook-style notifications
Template-based payloads
Dynamic data injection
Error callbacks
Completion tracking

Example Commands

Firecrawl Monitoring

/polling monitor website crawl job and notify when complete

Video Processing

/polling wait for video analysis to complete with 5-minute timeout

API Monitoring

/polling check service health every minute until restored

Data Processing

/polling monitor analysis job and extract results when ready

Polling Configuration

Start Polling Job

// POST to /polling/start
{
  "callbackUrlToken": "your callback token",
  "callbackUrl": "https://your-app.com/callback",
  "expectedResultPattern": {
    "type": "path",
    "pattern": "result.output.text"
  },
  "callbackPayload": {
    "message": "Job completed",
    "data": "{{results.result.output.text}}"
  },
  "pollUrl": "https://api.example.com/job/status",
  "pollUrlToken": "your polling token",
  "pollTime": "5m",
  "pollFrequency": "30s"
}

Start Response

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

Pattern Matching

Path Pattern

{
  "type": "path",
  "pattern": "result.output.text"
}

Use Cases:

Check if result.status exists
Verify data.items[0].id is present
Confirm response.completed is available

String Match Pattern

{
  "type": "stringMatch",
  "pattern": "completed successfully"
}

Use Cases:

Look for “processing complete” in response
Find “success” status messages
Match specific completion indicators

Callback Payloads

Template System

Use {{results}} to inject polling results into your callback payload:

Direct Result Injection

{
  "status": "completed",
  "result": "{{results}}"
}

Path-Based Injection

{
  "message": "Job completed with status: {{results.status}}",
  "output": "{{results.result.output.text}}"
}

Mixed Templates

{
  "notification": "Processing finished: {{results.message}}",
  "data": "{{results.data}}",
  "timestamp": "2023-10-18T10:30:00Z"
}

Time Configuration

Poll Time (Total Duration)

Range: 1m to 12h
Examples: “1m”, “30m”, “2h”, “5h30m”
Units: s (seconds), m (minutes), h (hours)

Poll Frequency (Check Interval)

Allowed Values: “5s”, ”10s”, ”20s”, ”30s”, “1m”, “3m”, “5m”
Must be shorter than poll time
Determines check frequency

Job Status Monitoring

Get Job Status

// GET /polling/status/{jobId}

Status Response

{
  "id": "poll_1234567890_abc123",
  "status": "active",
  "attempts": 5,
  "maxAttempts": 10,
  "startTime": 1634567890000,
  "endTime": 1634567920000,
  "duration": 30000,
  "lastError": "error message if any"
}

Status Types

active: Currently polling
completed: Successfully completed
failed: Failed with error
timeout: Exceeded poll time

Common Use Cases

Firecrawl Website Crawling

{
  "callbackUrlToken": "your callback token",
  "pollUrlToken": "your polling token",
  "callbackUrl": "https://mcpurlfornkfish/agentid/{agent-id}/chatid/{chat-id}",
  "expectedResultPattern": {
    "type": "path",
    "pattern": "status"
  },
  "callbackPayload": {
    "crawlId": "{{results.id}}",
    "status": "{{results.status}}",
    "totalPages": "{{results.total}}",
    "completedPages": "{{results.completed}}",
    "creditsUsed": "{{results.creditsUsed}}",
    "data": "{{results.data}}",
    "message": "Website crawl completed: {{results.completed}}/{{results.total}} pages processed"
  },
  "pollUrl": "https://api.firecrawl.dev/v1/crawl/123-456-789",
  "pollTime": "15m",
  "pollFrequency": "30s"
}

Video Processing

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

Data Analysis Job

{
  "callbackUrlToken": "your callback token",
  "pollUrlToken": "your polling token",
  "callbackUrl": "https://your-app.com/analysis-complete",
  "expectedResultPattern": {
    "type": "path",
    "pattern": "analysis.results.insights"
  },
  "callbackPayload": {
    "analysisId": "analysis-789",
    "insights": "{{results.analysis.results.insights}}",
    "summary": "Analysis completed with {{results.analysis.results.dataPoints}} data points"
  },
  "pollUrl": "https://analytics.com/jobs/analysis-789",
  "pollTime": "1h",
  "pollFrequency": "2m"
}

Error Handling

Automatic Error Handling

The polling service handles:

HTTP 4xx errors: Stops polling, sends error callback
HTTP 5xx errors: Retries according to frequency
Network timeouts: Retries according to frequency
Pattern match failures: Continues polling until timeout
Job timeout: Sends timeout callback

Error Callback

{
  ...originalCallbackPayload,
  "error": "Error description",
  "attempts": 5,
  "duration": 300000
}

Best Practices

Frequency Selection

Fast jobs (< 1 min): Use 5s or 10s frequency
Medium jobs (1-10 min): Use 30s frequency
Long jobs (> 10 min): Use 1m+ frequency

Poll URL Design

Return consistent JSON structure
Include status information
Provide progress indicators
Return error details for failures

Pattern Matching

Use path patterns for structured responses
Prefer specific paths over generic ones
Test patterns with sample data
Include fallback validation

Callback Payloads

Keep payloads concise but informative
Test template paths with sample data
Include error handling information
Provide completion timestamps

Performance Optimization

Efficient Polling

Choose appropriate frequencies
Set realistic timeouts
Monitor resource usage
Implement circuit breakers

Resource Management

Limit concurrent polling jobs
Clean up completed jobs
Monitor memory usage
Implement job queuing

Integration Patterns

Webhook Integration

// Use polling as webhook alternative
{
  "callbackUrl": "https://your-app.com/webhook-endpoint",
  "callbackPayload": {
    "event": "job.completed",
    "data": "{{results}}"
  }
}

Automation Workflows

// Chain with other automation steps
{
  "callbackUrl": "https://automation.com/next-step",
  "callbackPayload": {
    "trigger": "continue-workflow",
    "input": "{{results.output}}"
  }
}

Security Considerations

Token Management

Use secure callback tokens
Rotate tokens regularly
Validate token permissions
Monitor token usage

URL Validation

Validate callback URLs
Use HTTPS endpoints
Implement rate limiting
Monitor for abuse

Tips

Use INTERNAL_SKILL_URL + ‘polling’ as the base URL (mandatory)
Set realistic poll times based on expected completion duration
Choose poll frequency based on job type and urgency
Test template paths with sample response data before deployment
Include error information in callback payloads for debugging
Monitor polling job status to ensure proper completion
Design poll URLs to return consistent, structured responses

On this page

Basic Usage
Key Features
Long-Running Operations
Pattern Matching
Callback System
Example Commands
Firecrawl Monitoring
Video Processing
API Monitoring
Data Processing
Polling Configuration
Start Polling Job
Start Response
Pattern Matching
Path Pattern
String Match Pattern
Callback Payloads
Template System
Direct Result Injection
Path-Based Injection
Mixed Templates
Time Configuration
Poll Time (Total Duration)
Poll Frequency (Check Interval)
Job Status Monitoring
Get Job Status
Status Response
Status Types
Common Use Cases
Firecrawl Website Crawling
Video Processing
Data Analysis Job
Error Handling
Automatic Error Handling
Error Callback
Best Practices
Frequency Selection
Poll URL Design
Pattern Matching
Callback Payloads
Performance Optimization
Efficient Polling
Resource Management
Integration Patterns
Webhook Integration
Automation Workflows
Security Considerations
Token Management
URL Validation
Tips

The /polling command enables you to create long-running polling jobs that wait for external services to complete and trigger callbacks. Perfect for:

Long-running async operations
External service monitoring
Webhook-style callbacks
Background job processing
Service completion tracking

Basic Usage

Use the command to set up polling operations:

/polling monitor Firecrawl job until completion then notify

/polling wait for video processing to finish then send results

/polling check API status every 30 seconds for 10 minutes

Key Features

Long-Running Operations

Configurable polling duration (1m-12h)
Flexible polling frequency
Automatic retry handling
Error recovery
Timeout management

Pattern Matching

JSON path matching
String content matching
Flexible success criteria
Custom validation
Result extraction

Callback System

Webhook-style notifications
Template-based payloads
Dynamic data injection
Error callbacks
Completion tracking

Example Commands

Firecrawl Monitoring

/polling monitor website crawl job and notify when complete

Video Processing

/polling wait for video analysis to complete with 5-minute timeout

API Monitoring

/polling check service health every minute until restored

Data Processing

/polling monitor analysis job and extract results when ready

Polling Configuration

Start Polling Job

// POST to /polling/start
{
  "callbackUrlToken": "your callback token",
  "callbackUrl": "https://your-app.com/callback",
  "expectedResultPattern": {
    "type": "path",
    "pattern": "result.output.text"
  },
  "callbackPayload": {
    "message": "Job completed",
    "data": "{{results.result.output.text}}"
  },
  "pollUrl": "https://api.example.com/job/status",
  "pollUrlToken": "your polling token",
  "pollTime": "5m",
  "pollFrequency": "30s"
}

Start Response

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

Pattern Matching

Path Pattern

{
  "type": "path",
  "pattern": "result.output.text"
}

Use Cases:

Check if result.status exists
Verify data.items[0].id is present
Confirm response.completed is available

String Match Pattern

{
  "type": "stringMatch",
  "pattern": "completed successfully"
}

Use Cases:

Look for “processing complete” in response
Find “success” status messages
Match specific completion indicators

Callback Payloads

Template System

Use {{results}} to inject polling results into your callback payload:

Direct Result Injection

{
  "status": "completed",
  "result": "{{results}}"
}

Path-Based Injection

{
  "message": "Job completed with status: {{results.status}}",
  "output": "{{results.result.output.text}}"
}

Mixed Templates

{
  "notification": "Processing finished: {{results.message}}",
  "data": "{{results.data}}",
  "timestamp": "2023-10-18T10:30:00Z"
}

Time Configuration

Poll Time (Total Duration)

Range: 1m to 12h
Examples: “1m”, “30m”, “2h”, “5h30m”
Units: s (seconds), m (minutes), h (hours)

Poll Frequency (Check Interval)

Allowed Values: “5s”, ”10s”, ”20s”, ”30s”, “1m”, “3m”, “5m”
Must be shorter than poll time
Determines check frequency

Job Status Monitoring

Get Job Status

// GET /polling/status/{jobId}

Status Response

{
  "id": "poll_1234567890_abc123",
  "status": "active",
  "attempts": 5,
  "maxAttempts": 10,
  "startTime": 1634567890000,
  "endTime": 1634567920000,
  "duration": 30000,
  "lastError": "error message if any"
}

Status Types

active: Currently polling
completed: Successfully completed
failed: Failed with error
timeout: Exceeded poll time

Common Use Cases

Firecrawl Website Crawling

{
  "callbackUrlToken": "your callback token",
  "pollUrlToken": "your polling token",
  "callbackUrl": "https://mcpurlfornkfish/agentid/{agent-id}/chatid/{chat-id}",
  "expectedResultPattern": {
    "type": "path",
    "pattern": "status"
  },
  "callbackPayload": {
    "crawlId": "{{results.id}}",
    "status": "{{results.status}}",
    "totalPages": "{{results.total}}",
    "completedPages": "{{results.completed}}",
    "creditsUsed": "{{results.creditsUsed}}",
    "data": "{{results.data}}",
    "message": "Website crawl completed: {{results.completed}}/{{results.total}} pages processed"
  },
  "pollUrl": "https://api.firecrawl.dev/v1/crawl/123-456-789",
  "pollTime": "15m",
  "pollFrequency": "30s"
}

Video Processing

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

Data Analysis Job

{
  "callbackUrlToken": "your callback token",
  "pollUrlToken": "your polling token",
  "callbackUrl": "https://your-app.com/analysis-complete",
  "expectedResultPattern": {
    "type": "path",
    "pattern": "analysis.results.insights"
  },
  "callbackPayload": {
    "analysisId": "analysis-789",
    "insights": "{{results.analysis.results.insights}}",
    "summary": "Analysis completed with {{results.analysis.results.dataPoints}} data points"
  },
  "pollUrl": "https://analytics.com/jobs/analysis-789",
  "pollTime": "1h",
  "pollFrequency": "2m"
}

Error Handling

Automatic Error Handling

The polling service handles:

HTTP 4xx errors: Stops polling, sends error callback
HTTP 5xx errors: Retries according to frequency
Network timeouts: Retries according to frequency
Pattern match failures: Continues polling until timeout
Job timeout: Sends timeout callback

Error Callback

{
  ...originalCallbackPayload,
  "error": "Error description",
  "attempts": 5,
  "duration": 300000
}

Best Practices

Frequency Selection

Fast jobs (< 1 min): Use 5s or 10s frequency
Medium jobs (1-10 min): Use 30s frequency
Long jobs (> 10 min): Use 1m+ frequency

Poll URL Design

Return consistent JSON structure
Include status information
Provide progress indicators
Return error details for failures

Pattern Matching

Use path patterns for structured responses
Prefer specific paths over generic ones
Test patterns with sample data
Include fallback validation

Callback Payloads

Keep payloads concise but informative
Test template paths with sample data
Include error handling information
Provide completion timestamps

Performance Optimization

Efficient Polling

Choose appropriate frequencies
Set realistic timeouts
Monitor resource usage
Implement circuit breakers

Resource Management

Limit concurrent polling jobs
Clean up completed jobs
Monitor memory usage
Implement job queuing

Integration Patterns

Webhook Integration

// Use polling as webhook alternative
{
  "callbackUrl": "https://your-app.com/webhook-endpoint",
  "callbackPayload": {
    "event": "job.completed",
    "data": "{{results}}"
  }
}

Automation Workflows

// Chain with other automation steps
{
  "callbackUrl": "https://automation.com/next-step",
  "callbackPayload": {
    "trigger": "continue-workflow",
    "input": "{{results.output}}"
  }
}

Security Considerations

Token Management

Use secure callback tokens
Rotate tokens regularly
Validate token permissions
Monitor token usage

URL Validation

Validate callback URLs
Use HTTPS endpoints
Implement rate limiting
Monitor for abuse

Tips

Use INTERNAL_SKILL_URL + ‘polling’ as the base URL (mandatory)
Set realistic poll times based on expected completion duration
Choose poll frequency based on job type and urgency
Test template paths with sample response data before deployment
Include error information in callback payloads for debugging
Monitor polling job status to ensure proper completion
Design poll URLs to return consistent, structured responses

On this page

Basic Usage
Key Features
Long-Running Operations
Pattern Matching
Callback System
Example Commands
Firecrawl Monitoring
Video Processing
API Monitoring
Data Processing
Polling Configuration
Start Polling Job
Start Response
Pattern Matching
Path Pattern
String Match Pattern
Callback Payloads
Template System
Direct Result Injection
Path-Based Injection
Mixed Templates
Time Configuration
Poll Time (Total Duration)
Poll Frequency (Check Interval)
Job Status Monitoring
Get Job Status
Status Response
Status Types
Common Use Cases
Firecrawl Website Crawling
Video Processing
Data Analysis Job
Error Handling
Automatic Error Handling
Error Callback
Best Practices
Frequency Selection
Poll URL Design
Pattern Matching
Callback Payloads
Performance Optimization
Efficient Polling
Resource Management
Integration Patterns
Webhook Integration
Automation Workflows
Security Considerations
Token Management
URL Validation
Tips

​Basic Usage

​Key Features

​Long-Running Operations

​Pattern Matching

​Callback System

​Example Commands

​Firecrawl Monitoring

​Video Processing

​API Monitoring

​Data Processing

​Polling Configuration

​Start Polling Job

​Start Response

​Pattern Matching

​Path Pattern

​String Match Pattern

​Callback Payloads

​Template System

​Direct Result Injection

​Path-Based Injection

​Mixed Templates

​Time Configuration

​Poll Time (Total Duration)

​Poll Frequency (Check Interval)

​Job Status Monitoring

​Get Job Status

​Status Response

​Status Types

​Common Use Cases

​Firecrawl Website Crawling

​Video Processing

​Data Analysis Job

​Error Handling

​Automatic Error Handling

​Error Callback

​Best Practices

​Frequency Selection

​Poll URL Design

​Pattern Matching

​Callback Payloads

​Performance Optimization

​Efficient Polling

​Resource Management

​Integration Patterns

​Webhook Integration

​Automation Workflows

​Security Considerations

​Token Management

​URL Validation

​Tips

API Documentation

​Basic Usage

​Key Features

​Long-Running Operations

​Pattern Matching

​Callback System

​Example Commands

​Firecrawl Monitoring

​Video Processing

​API Monitoring

​Data Processing

​Polling Configuration

​Start Polling Job

​Start Response

​Pattern Matching

​Path Pattern

​String Match Pattern

​Callback Payloads

​Template System

​Direct Result Injection

​Path-Based Injection

​Mixed Templates

​Time Configuration

​Poll Time (Total Duration)

​Poll Frequency (Check Interval)

​Job Status Monitoring

​Get Job Status

​Status Response

​Status Types

​Common Use Cases

Basic Usage

Key Features

Long-Running Operations

Pattern Matching

Callback System

Example Commands

Firecrawl Monitoring

Video Processing

API Monitoring

Data Processing

Polling Configuration

Start Polling Job

Start Response

Pattern Matching

Path Pattern

String Match Pattern

Callback Payloads

Template System

Direct Result Injection

Path-Based Injection

Mixed Templates

Time Configuration

Poll Time (Total Duration)

Poll Frequency (Check Interval)

Job Status Monitoring

Get Job Status

Status Response

Status Types

Common Use Cases

Firecrawl Website Crawling

Video Processing

Data Analysis Job

Error Handling

Automatic Error Handling

Error Callback

Best Practices

Frequency Selection

Poll URL Design

Pattern Matching

Callback Payloads

Performance Optimization

Efficient Polling

Resource Management

Integration Patterns

Webhook Integration

Automation Workflows

Security Considerations

Token Management

URL Validation

Tips

Basic Usage

Key Features

Long-Running Operations

Pattern Matching

Callback System

Example Commands

Firecrawl Monitoring

Video Processing

API Monitoring

Data Processing

Polling Configuration

Start Polling Job

Start Response

Pattern Matching

Path Pattern

String Match Pattern

Callback Payloads

Template System

Direct Result Injection

Path-Based Injection

Mixed Templates

Time Configuration

Poll Time (Total Duration)

Poll Frequency (Check Interval)

Job Status Monitoring

Get Job Status

Status Response

Status Types

Common Use Cases

Firecrawl Website Crawling