Execution

When you execute a task, Linkt creates a run that tracks the workflow from start to finish. This page explains how execution works, run states, output formats, and best practices for monitoring workflows.

Task to Run Relationship

Tasks and runs have a one-to-many relationship:

A Task is a reusable workflow template that defines what to do and how to do it
A Run is a single execution instance of a task
Each time you execute a task, a new run is created
Multiple runs can exist for the same task

Loading diagram...

Executing a Task

To execute a task, call the execute endpoint:

curl -X POST "https://api.linkt.ai/v1/task/{task_id}/execute" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "icp_id": "507f1f77bcf86cd799439011",
    "parameters": {}
  }'

Response:

{
  "run_id": "507f1f77bcf86cd799439014",
  "flow_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SCHEDULED"
}

Use the returned run_id to monitor execution progress.

Run States

Runs progress through a state machine from creation to completion (or failure):

Status	Description	Terminal?
`SCHEDULED`	Run created, queued for execution	No
`PENDING`	Run preparing, resources being allocated	No
`RUNNING`	Workflow actively executing	No
`COMPLETED`	Workflow finished successfully	Yes
`FAILED`	Workflow encountered an error	Yes
`CANCELED`	Run was manually canceled	Yes
`CRASHED`	Run crashed unexpectedly	Yes
`PAUSED`	Run is paused (rare)	No

State Flow

Loading diagram...

Most runs follow the happy path: SCHEDULED → PENDING → RUNNING → COMPLETED.

Terminal States

Terminal states (COMPLETED, FAILED, CANCELED, CRASHED) are final—the run will not change status again. Use these to determine when to stop polling.

Run Structure

A complete run object contains:

{
  "id": "507f1f77bcf86cd799439014",
  "task_id": "507f1f77bcf86cd799439013",
  "icp_id": "507f1f77bcf86cd799439011",
  "task_type": "search",
  "flow_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "input": {
    "icp_id": "507f1f77bcf86cd799439011"
  },
  "output": {
    "version": "1.0",
    "credits": {
      "total_credits": 150.0,
      "breakdown": {
        "search_company": 100.0,
        "enrich_company": 50.0
      }
    },
    "resources": {
      "entities_created": ["entity_id_1", "entity_id_2"],
      "entities_updated": [],
      "signals_created": []
    },
    "run_time": 45.2
  },
  "error": null,
  "created_at": "2025-01-05T12:00:15Z",
  "updated_at": "2025-01-05T12:01:00Z"
}

Fields

Field	Type	Description
`id`	string	Unique run identifier
`task_id`	string	Parent task ID
`icp_id`	string	ICP used for this execution (optional)
`task_type`	string	Workflow type: `search`, `signal`, `profile`, `ingest`
`flow_run_id`	string	Internal workflow engine ID
`status`	string	Current run state
`input`	object	Parameters passed at execution time
`output`	object	Structured output (see below)
`error`	string	Error message if failed (null otherwise)
`created_at`	datetime	When the run was created
`updated_at`	datetime	When the run was last updated

Structured Output

When a run completes, the output field contains structured results with credit usage and resource tracking:

{
  "version": "1.0",
  "credits": {
    "total_credits": 150.0,
    "breakdown": {
      "search_company": 100.0,
      "enrich_company": 50.0
    }
  },
  "resources": {
    "entities_created": ["507f1f77bcf86cd799439015", "507f1f77bcf86cd799439016"],
    "entities_updated": ["507f1f77bcf86cd799439017"],
    "signals_created": []
  },
  "run_time": 45.2
}

Credit Usage

The credits object tracks consumption:

Field	Type	Description
`total_credits`	number	Total credits consumed by this run
`breakdown`	object	Credits by action type (e.g., `search_company`, `enrich_person`)

Common action types in breakdown:

search_company — Company discovery searches
search_person — Person discovery searches
enrich_company — Company data enrichment
enrich_person — Person data enrichment

Resource Tracking

The resources object tracks what was created or modified:

Field	Type	Description
`entities_created`	array	IDs of newly created entities
`entities_updated`	array	IDs of entities that were updated
`signals_created`	array	IDs of newly created signals

Use these IDs to retrieve the actual data from the entities or signals endpoints.

Run Time

The run_time field contains the total execution duration in seconds.

Polling for Status

To monitor a run, poll the run endpoint until it reaches a terminal state:

import time
import requests
 
def wait_for_completion(run_id, api_key, max_wait=1800, poll_interval=10):
    """
    Poll run status until completion or timeout.
 
    Args:
        run_id: The run ID to monitor
        api_key: Your API key
        max_wait: Maximum seconds to wait (default 30 minutes)
        poll_interval: Seconds between polls (default 10)
 
    Returns:
        The completed run object
 
    Raises:
        Exception if run fails, is canceled, or times out
    """
    headers = {"x-api-key": api_key}
    url = f"https://api.linkt.ai/v1/run/{run_id}"
 
    terminal_states = {"COMPLETED", "FAILED", "CANCELED", "CRASHED"}
    start = time.time()
 
    while time.time() - start < max_wait:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        run = response.json()
 
        status = run["status"]
 
        if status == "COMPLETED":
            return run
        elif status in terminal_states:
            error = run.get("error", "Unknown error")
            raise Exception(f"Run {status}: {error}")
 
        time.sleep(poll_interval)
 
    raise Exception(f"Timeout after {max_wait}s waiting for run {run_id}")

Polling Interval

A 10-second interval balances responsiveness with API efficiency. More frequent polling doesn't speed up execution and increases API usage. Since workflows can run for 15-20+ minutes, polling less frequently is recommended.

JavaScript Example

async function waitForCompletion(runId, apiKey, maxWait = 1800000) {
  // maxWait default: 30 minutes (in milliseconds)
  const terminalStates = new Set(['COMPLETED', 'FAILED', 'CANCELED', 'CRASHED']);
  const startTime = Date.now();
 
  while (Date.now() - startTime < maxWait) {
    const response = await fetch(`https://api.linkt.ai/v1/run/${runId}`, {
      headers: { 'x-api-key': apiKey }
    });
 
    const run = await response.json();
 
    if (run.status === 'COMPLETED') {
      return run;
    }
 
    if (terminalStates.has(run.status)) {
      throw new Error(`Run ${run.status}: ${run.error || 'Unknown error'}`);
    }
 
    await new Promise(resolve => setTimeout(resolve, 10000)); // Poll every 10 seconds
  }
 
  throw new Error(`Timeout waiting for run ${runId}`);
}

Canceling a Run

To cancel a running workflow:

curl -X POST "https://api.linkt.ai/v1/run/{run_id}/cancel" \
  -H "x-api-key: your-api-key"

Response: 204 No Content

Cancellation

Cancellation is only effective for non-terminal runs. Once a run reaches COMPLETED, FAILED, or CRASHED, it cannot be canceled.

Run Queue

For long-running workflows, you can monitor the processing queue to see entities being worked on:

curl -X GET "https://api.linkt.ai/v1/run/{run_id}/queue?limit=20" \
  -H "x-api-key: your-api-key"

Query Parameters:

Parameter	Default	Description
`offset`	0	Starting position in queue
`limit`	20	Maximum entities to return (1-100)
`state`	—	Filter by state: `queued`, `processing`, `completed`, `discarded`
`include_history`	false	Include entities from all states

Entity Queue States:

State	Description
`queued`	Waiting to be processed
`processing`	Currently being worked on
`completed`	Successfully processed and saved
`discarded`	Skipped (not qualified)

Error Handling

When a run fails, follow these steps:

1. Check Error Details

The run response includes error information:

{
  "status": "FAILED",
  "error": "Rate limit exceeded for provider X"
}

2. Common Failure Reasons

Error Type	Cause	Resolution
Rate limit	Too many requests to external providers	Wait and retry
Invalid configuration	ICP or task misconfigured	Review settings
Sheet capacity	Sheet at entity limit	Increase limit or use new sheet
Timeout	Workflow took too long	Reduce batch size
Provider error	External API unavailable	Retry later

3. Retry Strategy

For transient errors, implement exponential backoff:

import time
 
def execute_with_retry(task_id, icp_id, api_key, max_retries=3):
    headers = {"x-api-key": api_key, "Content-Type": "application/json"}
    url = f"https://api.linkt.ai/v1/task/{task_id}/execute"
 
    for attempt in range(max_retries):
        # Execute task
        response = requests.post(url, headers=headers, json={"icp_id": icp_id})
        run = response.json()
 
        # Wait for completion
        try:
            return wait_for_completion(run["run_id"], api_key)
        except Exception as e:
            if "Rate limit" in str(e) and attempt < max_retries - 1:
                wait_time = (2 ** attempt) * 30  # 30s, 60s, 120s
                print(f"Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

Expected Durations

Different workflow types have different typical durations:

Task Type	Typical Duration	Notes
Search	15-20+ minutes	Can take longer depending on ICP complexity and desired entity count
CSV ingest	~1 minute per row	~15 rows takes ~15 minutes
Signal monitoring	Varies	Depends on `monitoring_frequency` configured in task

Allow Sufficient Time

Search and ingest workflows involve AI-powered research that takes time to complete thoroughly. Set your polling timeout to at least 30 minutes for search tasks and scale accordingly for larger ingest batches.

Listing Runs

Query runs with filtering:

curl -X GET "https://api.linkt.ai/v1/run?task_id={task_id}&status=COMPLETED" \
  -H "x-api-key: your-api-key"

Query Parameters:

Parameter	Description
`task_id`	Filter by task
`icp_id`	Filter by ICP
`status`	Filter by status
`task_type`	Filter by type: `search`, `signal`, `profile`, `ingest`
`created_after`	ISO 8601 datetime
`created_before`	ISO 8601 datetime
`page`	Page number (default: 1)
`page_size`	Results per page (default: 20, max: 100)
`sort_by`	Sort field
`order`	-1 (descending) or 1 (ascending)

Next Steps

Tasks — Configure workflow templates
Runs — Run data structure reference
Quickstart — See execution in practice
API Reference — Complete run endpoint documentation

On this page