Tasks

A Task defines the configuration for a research workflow. Tasks specify what type of operation to perform and how to execute it.

What is a Task?

Tasks are reusable workflow templates that:

Define the type of research operation (search, enrich, monitor)
Reference an ICP for targeting criteria
Specify configuration parameters
Can be executed multiple times to create runs

Task Structure

{
  "id": "507f1f77bcf86cd799439013",
  "name": "Enterprise SaaS Company Search",
  "description": "Search for B2B SaaS companies",
  "flow_name": "search",
  "deployment_name": "main",
  "icp_id": "507f1f77bcf86cd799439011",
  "task_config": {
    "version": "v3.0",
    "config_type": "search-task",
    "desired_contact_count": 1,
    "user_feedback": ""
  }
}

Flow Names

The flow_name field determines what type of workflow the task executes:

Flow Name	Purpose	Config Type
`search`	Discover new entities matching ICP criteria	`search-task`
`signal-topic`	Monitor topics for business signals	`signal-topic`
`signal-csv`	Generate signals from uploaded CSV data	`signal-csv`
`signal-sheet`	Monitor existing sheet entities for signals	`signal-sheet`
`ingest`	Import and enrich entities from CSV files	`ingest-task`

Deployment Name

The deployment_name must always be set to "main". Do not modify this value.

Task Configurations

Each flow type requires a specific configuration structure. The config_type field must match the flow.

Search Task Configuration

For discovering new companies matching your ICP:

{
  "version": "v3.0",
  "config_type": "search-task",
  "desired_contact_count": 1,
  "user_feedback": ""
}

Field	Type	Description
`version`	string	Configuration version (use `v3.0`)
`config_type`	string	Must be `search-task`
`desired_contact_count`	integer	Number of contacts to find per company (0 for companies only)
`user_feedback`	string	Optional feedback to refine search results
`webhook_url`	string	Optional HTTPS URL for completion notifications (see Webhooks)

Signal Topic Configuration

For monitoring topics across the web for business signals:

{
  "version": "v1.0",
  "config_type": "signal-topic",
  "topics": ["AI funding", "Series B"],
  "signal_types": ["funding", "leadership_change"]
}

Field	Type	Description
`config_type`	string	Must be `signal-topic`
`topics`	array	Keywords and phrases to monitor
`signal_types`	array	Types of signals to detect
`webhook_url`	string	Optional HTTPS URL for completion notifications (see Webhooks)

Signal CSV Configuration

For generating signals from uploaded CSV data:

{
  "version": "v1.0",
  "config_type": "signal-csv",
  "file_id": "507f1f77bcf86cd799439030",
  "signal_types": ["funding", "product_launch"]
}

Field	Type	Description
`config_type`	string	Must be `signal-csv`
`file_id`	string	ID of uploaded CSV file (see Files)
`signal_types`	array	Types of signals to detect
`webhook_url`	string	Optional HTTPS URL for completion notifications (see Webhooks)

Signal Sheet Configuration

For monitoring existing entities in a sheet for signals:

{
  "version": "v1.0",
  "config_type": "signal-sheet",
  "sheet_id": "507f1f77bcf86cd799439012",
  "signal_types": ["funding", "hiring_surge", "leadership_change"]
}

Field	Type	Description
`config_type`	string	Must be `signal-sheet`
`sheet_id`	string	ID of sheet to monitor
`signal_types`	array	Types of signals to detect
`webhook_url`	string	Optional HTTPS URL for completion notifications (see Webhooks)

Ingest Task Configuration

For importing and enriching entities from CSV files:

{
  "version": "v1.0",
  "config_type": "ingest-task",
  "file_id": "507f1f77bcf86cd799439030",
  "primary_column": "company_name",
  "csv_entity_type": "company"
}

Field	Type	Description
`config_type`	string	Must be `ingest-task`
`file_id`	string	ID of uploaded CSV file (see Files)
`primary_column`	string	CSV column containing entity identifier
`csv_entity_type`	string	Type of entities in CSV (`company` or `person`)
`webhook_url`	string	Optional HTTPS URL for completion notifications (see Webhooks)

Configuration Versioning

Task configurations use semantic versioning. Always use the latest stable version:

Config Type	Current Version
`search-task`	`v3.0`
`signal-topic`	`v1.0`
`signal-csv`	`v1.0`
`signal-sheet`	`v1.0`
`ingest-task`	`v1.0`

Version Compatibility

Older configuration versions continue to work, but new features are only available in the latest versions.

Task Execution

When you execute a task, a Run is created to track the execution. The run contains:

Status updates as the workflow progresses
Results including discovered entities or signals
Resource usage metrics (credits, entities created)

See Runs for details on monitoring execution.

Next Steps

Runs - Monitor task execution
Webhooks - Receive completion notifications
ICPs - Define targeting criteria
Signals - Understanding signal outputs
API Reference - Complete task endpoint documentation

On this page