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": {
    "type": "search",
    "desired_contact_count": 1,
    "user_feedback": ""
  }
}

Flow Names

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

Flow Name	Purpose	Task Type
`search`	Discover new entities matching ICP criteria	`search`
`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`

Deployment Name

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

Field	Type	Required	Default	Description
`type`	`"search"`	Yes	—	Configuration type discriminator
`desired_contact_count`	integer	No	1	Number of contacts to find per company (minimum: 1)
`user_feedback`	string	No	`""`	Feedback to refine search results
`webhook_url`	string	No	—	HTTPS URL for completion notifications (see Webhooks)

Search tasks require an ICP configured with both company and person entity targets. You must also create two sheets linked to the ICP—one for companies and one for persons. The desired_contact_count must be at least 1.

Signal Topic Configuration

For monitoring topics across the web for business signals:

{
  "type": "signal-topic",
  "topic_criteria": "AI startups raising Series A funding",
  "signal_types": [
    {"type": "funding", "criteria": "Series A or later rounds"}
  ],
  "entity_type": "company",
  "monitoring_frequency": "weekly",
  "geographic_filters": ["United States"],
  "industry_filters": ["Technology"]
}

Field	Type	Required	Default	Description
`type`	`"signal-topic"`	Yes	—	Configuration type discriminator
`topic_criteria`	string	Yes	—	Natural language description of what to monitor
`signal_types`	SignalTypeConfig[]	Yes	—	Array of signal type objects with `type` and `criteria` fields
`entity_type`	string	No	`"company"`	Entity type to monitor (`"company"` or `"person"`)
`monitoring_frequency`	string	No	`"weekly"`	How often to check: `"daily"`, `"weekly"`, or `"monthly"`
`geographic_filters`	string[]	No	—	Geographic regions to focus on
`industry_filters`	string[]	No	—	Industries to filter by
`company_size_filters`	string[]	No	—	Company size criteria
`webhook_url`	string	No	—	HTTPS URL for completion notifications (see Webhooks)

Signal CSV Configuration

For generating signals from uploaded CSV data:

{
  "type": "signal-csv",
  "file_id": "507f1f77bcf86cd799439030",
  "signal_types": [
    {"type": "hiring_surge", "criteria": "Engineering team growth > 20%"}
  ],
  "entity_type": "company",
  "primary_column": "name",
  "monitoring_frequency": "weekly"
}

Field	Type	Required	Default	Description
`type`	`"signal-csv"`	Yes	—	Configuration type discriminator
`file_id`	string	Yes	—	ID of uploaded CSV file (see Files)
`signal_types`	SignalTypeConfig[]	Yes	—	Array of signal type objects with `type` and `criteria` fields
`entity_type`	string	No	`"company"`	Entity type in the CSV (`"company"` or `"person"`)
`primary_column`	string	No	`"name"`	CSV column containing entity names
`monitoring_frequency`	string	No	`"weekly"`	How often to check: `"daily"`, `"weekly"`, or `"monthly"`
`webhook_url`	string	No	—	HTTPS URL for completion notifications (see Webhooks)

Signal Sheet Configuration

For monitoring existing entities from an ICP's discovery results:

{
  "type": "signal-sheet",
  "source_icp_id": "507f1f77bcf86cd799439011",
  "signal_types": [
    {"type": "leadership_change", "criteria": "C-level departures or appointments"}
  ],
  "entity_type": "company",
  "entity_filters": {"industry": "Technology"},
  "monitoring_frequency": "weekly"
}

Field	Type	Required	Default	Description
`type`	`"signal-sheet"`	Yes	—	Configuration type discriminator
`source_icp_id`	string	Yes	—	ID of the Discovery ICP whose entities to monitor
`signal_types`	SignalTypeConfig[]	Yes	—	Array of signal type objects with `type` and `criteria` fields
`entity_type`	string	No	`"company"`	Entity type to monitor (`"company"` or `"person"`)
`entity_filters`	object	No	—	MongoDB-style query to filter which entities to monitor
`monitoring_frequency`	string	No	`"weekly"`	How often to check: `"daily"`, `"weekly"`, or `"monthly"`
`webhook_url`	string	No	—	HTTPS URL for completion notifications (see Webhooks)

Field Name

The field is source_icp_id, not sheet_id. This references the ICP whose discovered entities you want to monitor.

Ingest Task Configuration

For importing and enriching entities from CSV files:

{
  "type": "ingest",
  "file_id": "507f1f77bcf86cd799439030",
  "primary_column": "company_name",
  "csv_entity_type": "company"
}

Field	Type	Required	Default	Description
`type`	`"ingest"`	Yes	—	Configuration type discriminator
`file_id`	string	Yes	—	ID of uploaded CSV file (see Files)
`primary_column`	string	Yes	—	CSV column containing entity identifier
`csv_entity_type`	string	Yes	—	Type of entities in CSV (`"company"` or `"person"`)
`webhook_url`	string	No	—	HTTPS URL for completion notifications (see Webhooks)

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