Skip to main content

Trigger from API Polling

ComponentTypeDescription
imgTrigger from API Polling▶️ triggerpoll an API endpoint at regular intervals and trigger a workflow when a success response is received

The Trigger from API Polling component allows you to trigger a workflow by polling an external API or URL at regular intervals. When the API returns a configured success status code (e.g., 200), the workflow is triggered. This is useful for integrating with external systems that don't support webhooks, or for monitoring APIs for specific conditions.

Configuration​

API Endpoint URL​

Enter the URL of the API endpoint to poll. You can use placeholders for dynamic values, including:

  • Secrets: Type $ to insert secrets stored in your credential store (e.g., ${API_KEY.SECRET})
  • Session ID: Use ${SESSION_ID} to include the workflow session ID in your request, allowing you to correlate requests with workflow sessions

The URL field supports the mention editor, so you can easily browse and insert available placeholders and secrets by typing $.

HTTP Method​

Select the HTTP method to use for polling:

  • GET - Retrieve data from the endpoint (default)
  • POST - Send data to the endpoint
  • PUT - Update data at the endpoint
  • DELETE - Delete data at the endpoint

Headers​

Add custom HTTP headers to include with each poll request. Click the + button to add key-value pairs. Header values support placeholders and secrets using the ${SECRET_NAME.SECRET} syntax.

Common headers include:

  • Authorization - For API authentication (e.g., Bearer ${API_TOKEN.SECRET})
  • Content-Type - To specify the request content type (e.g., application/json)
  • Accept - To specify expected response format
  • X-API-Key - For API key authentication

Query Parameters​

Add URL query parameters to include with each poll request. Click the + button to add key-value pairs. Parameter values support placeholders, secrets, and the session ID placeholder.

Example parameters:

  • page = 1
  • limit = 100
  • sessionId = ${SESSION_ID}

Request Body​

For POST and PUT requests, a request body field becomes available. Enter the request body content, which can be JSON, XML, or plain text depending on your API requirements. You can include secrets and placeholders in the request body.

Example JSON body:

{
  "sessionId": "${SESSION_ID}",
  "action": "check_status",
  "filters": {
    "status": "pending"
  }
}

Polling Interval​

Configure how often the API should be polled:

  • Interval Value - The number of time units between polls (minimum: 1)
  • Interval Type - Minutes, Hours, or Days

For example, setting the interval to 5 minutes means the API will be polled every 5 minutes. The minimum polling interval is 1 minute.

warning

Each poll consumes a workflow action, regardless of whether the success status code is matched. Consider your polling interval carefully to avoid excessive action consumption.

How Polling Works

The system checks for due polls every 60 seconds. When a poll is due (based on the configured interval since the last poll), the HTTP request is executed asynchronously. This means there may be a slight delay (up to 60 seconds) between when a poll is scheduled and when it actually executes.

Success Status Codes​

Configure which HTTP status codes should trigger the workflow to proceed. By default, common success codes are included:

  • 200 (OK)
  • 201 (Created)
  • 202 (Accepted)
  • 204 (No Content)

Additional status codes available in the dropdown:

  • 206 (Partial Content)
  • 301 (Moved Permanently)
  • 302 (Found)
  • 303 (See Other)
  • 304 (Not Modified)
  • 307 (Temporary Redirect)
  • 308 (Permanent Redirect)

You can also enter custom status codes by typing them directly. When a poll returns a status code that matches one of the configured success codes, the workflow proceeds to the next component.

note

Every poll creates a workflow session (consumes an action). If the poll does not match the success status codes, the session ends without proceeding to subsequent components. The poll attempt is still recorded in the history.

Response Format​

Select the expected response format:

  • JSON - Parse response as JSON (default)
  • XML - Parse response as XML
  • Plain Text - Treat response as plain text

The response format affects how the data is stored in the output placeholder. JSON responses are parsed and stored as structured data that can be accessed in subsequent components.

Output Placeholder​

Configure the placeholder key that will contain the API response data. This allows you to use the response data in subsequent workflow components.

The response data includes:

  • The parsed response body (based on the selected format)
  • The HTTP status code
  • Response headers (when available)

Using the Session ID Placeholder​

The ${SESSION_ID} placeholder is a special built-in placeholder that contains the workflow session ID. This is generated before the HTTP request is made, allowing you to:

  1. Include the session ID in your API request (URL, headers, query params, or body)
  2. Have the external system reference this session ID
  3. Correlate responses and callbacks with specific workflow sessions

Example use case: You're polling an external job processing system. By including ${SESSION_ID} in your request, the external system can tag its responses or callbacks with your workflow session ID for easy correlation.

The session ID appears in the placeholder dropdown at the top of the list when typing $ in any input field.

Polling Status​

The component UI displays the current polling status with a prominent banner at the top:

Active Status (Green)​

When the workflow is published:

  • Shows "Polling Active" with a green checkmark
  • Displays when the last poll occurred (e.g., "last poll: 5m ago")
  • Polling runs automatically at the configured interval

Inactive Status (Orange)​

When the workflow is not published:

  • Shows "Polling Inactive" with an orange warning icon
  • Message: "Polling will start when this workflow is published"
  • No polls are executed while inactive

Poll History​

The component displays recent poll activity in the "Recent Poll Activity" section. This helps you monitor and debug your polling configuration.

History Display​

Each poll entry shows:

  • Timestamp - When the poll was executed (e.g., "5m ago", "2h ago", or a specific date)
  • Status Code - The HTTP status code received (e.g., "Status 200") or "No response" if the request failed
  • Result - "Success" (green) if the status code matched, or "Not matched" (red) if it didn't
  • Error Message - If the request failed, the error details are displayed

Expandable Response Body​

For debugging purposes, you can view the API response for each poll:

  1. Click the expand arrow (▼) on any history entry that has a response
  2. The response body panel opens showing:
    • Response Body header with truncation indicator if applicable
    • Copy button - Click to copy the response to your clipboard
    • Formatted JSON - If the response is JSON, it's automatically formatted for readability
Response Size Limits

Large responses are automatically truncated to 10KB to ensure system performance. If a response was truncated, a "Truncated" badge appears next to the response header.

History Limits​

  • The system retains the last 50 poll attempts for each component
  • The UI displays up to 20 entries at a time
  • Use the Refresh button (↻) to load the latest poll history

Refresh History​

Click the refresh button next to "Recent Poll Activity" to fetch the latest poll history from the server. This is useful when:

  • You've just published a workflow and want to see the first polls
  • You want to verify recent poll activity
  • Debugging poll behavior

Best Practices​

  1. Set appropriate intervals - Don't poll more frequently than necessary to avoid excessive API calls and action consumption. Consider that each poll consumes a workflow action.

  2. Use secrets for sensitive data - Store API keys, tokens, and other credentials in the credential store and reference them using ${SECRET_NAME.SECRET}. Never hardcode sensitive values.

  3. Handle rate limits - Be aware of the target API's rate limits when configuring polling intervals. If the API has a rate limit of 100 requests per minute, don't poll more than once every 36 seconds to stay safe.

  4. Monitor poll history - Regularly check the poll history in the component UI to ensure polling is working as expected. Look for patterns in failures or unexpected responses.

  5. Use session IDs for correlation - Include ${SESSION_ID} in requests when you need to correlate external system responses with workflow sessions. This is especially useful for tracking long-running operations.

  6. Start with longer intervals - When testing a new polling configuration, start with longer intervals (e.g., 5-10 minutes) and decrease once you've confirmed the setup works correctly.

  7. Use the response body viewer - When debugging, expand poll history entries to view the actual API responses. Use the copy button to save responses for analysis.

  8. Configure appropriate success codes - If your API uses non-standard success codes (like 206 for partial content or 304 for caching), add them to the success codes list.

Troubleshooting​

IssuePossible CauseSolution
Polling not runningWorkflow not publishedPublish the workflow to activate polling
Workflow not triggeringStatus code not in success listAdd the returned status code to success codes
Wrong data in placeholderResponse format mismatchChange the response format setting (JSON/XML/Text)
Polls appear delayedNormal scheduler behaviorPolls are checked every 60 seconds; slight delays are normal
Empty response bodyAPI returns no contentCheck if the API requires different parameters or authentication
Authentication errorsExpired or invalid credentialsUpdate the secrets in the credential store
History not updatingCachingClick the refresh button to fetch latest history