Tasks

All operations require authentication using Bearer tokens. Make sure you have your API credentials ready.

Datasets enter locked mode during task execution and cannot be modified until completion.

Create New Rows Task

Generate and process new rows for your dataset with enrichment or AI generation.

curl -X POST "https://secure-api.getclaro.ai/api/v2/datasets/$DATASET_ID/tasks/new-rows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rowCount": 100,
    "webhookId": "$WEBHOOK_ID"
  }'

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "rowCount": 100,
    "webhookId": "your-webhook-id"  # Optional webhook for completion notification
}

dataset_id = "your-dataset-id"  # Replace with your dataset ID

response = requests.post(
    f"https://secure-api.getclaro.ai/api/v2/datasets/{dataset_id}/tasks/new-rows",
    headers=headers,
    json=data
)

const datasetId = "your-dataset-id"; // Replace with your dataset ID
const taskRequest = {
  rowCount: 100,
  webhookId: "your-webhook-id", // Optional webhook for completion notification
};

const response = await fetch(
  `https://secure-api.getclaro.ai/api/v2/datasets/${datasetId}/tasks/new-rows`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(taskRequest),
  }
);

{
  "taskId": "task_550e8400-e29b-41d4-a716-446655440000",
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "new_rows",
  "status": "queued",
  "rowCount": 100,
  "estimatedDuration": "5-10 minutes",
  "createdAt": "2024-03-14T15:30:00Z",
  "webhookId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

{
  "error": "Dataset is locked",
  "code": "DATASET_LOCKED",
  "details": {
    "message": "Dataset is currently being processed by another task",
    "activeTaskId": "task_123e4567-e89b-12d3-a456-426614174000"
  }
}

Create Bulk Processing Task

Process cells in your dataset with flexible targeting options. Process all empty cells, specific cells, entire columns/rows, or intersections of rows and columns.

# Process all empty cells in the dataset
curl -X POST "https://secure-api.getclaro.ai/api/v2/datasets/$DATASET_ID/tasks/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "processOnlyEmpty": true,
    "webhookId": "$WEBHOOK_ID"
  }'

# Process specific cells

curl -X POST "https://secure-api.getclaro.ai/api/v2/datasets/$DATASET_ID/tasks/bulk" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
"cellIds": ["cell_1", "cell_2"],
"webhookId": "$WEBHOOK_ID"
}'

# Process intersection of specific rows and columns

curl -X POST "https://secure-api.getclaro.ai/api/v2/datasets/$DATASET_ID/tasks/bulk" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
"rowIds": ["row_1", "row_2"],
"columnIds": ["col_product_name", "col_category"],
"processOnlyEmpty": true,
"webhookId": "$WEBHOOK_ID"
}'

import requests

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Example 1: Process all empty cells in the dataset
data = {
    "processOnlyEmpty": True,  # Process all empty cells (default: true)
    "webhookId": "your-webhook-id"  # Optional webhook for completion notification
}

# Example 2: Process specific cells
data = {
    "cellIds": ["cell_1", "cell_2"],  # Specific cell IDs to process
    "webhookId": "your-webhook-id"
}

# Example 3: Process intersection of rows and columns
data = {
    "rowIds": ["row_1", "row_2"],  # Specific rows
    "columnIds": ["col_product_name", "col_category"],  # Specific columns
    "processOnlyEmpty": True,  # Only process empty cells in the intersection
    "webhookId": "your-webhook-id"
}

dataset_id = "your-dataset-id"  # Replace with your dataset ID

response = requests.post(
    f"https://secure-api.getclaro.ai/api/v2/datasets/{dataset_id}/tasks/bulk",
    headers=headers,
    json=data
)

const datasetId = "your-dataset-id"; // Replace with your dataset ID

// Example 1: Process all empty cells in the dataset
const processAllEmpty = {
  processOnlyEmpty: true, // Process all empty cells (default: true)
  webhookId: "your-webhook-id", // Optional webhook for completion notification
};

// Example 2: Process specific cells
const processSpecificCells = {
  cellIds: ["cell_1", "cell_2"], // Specific cell IDs to process
  webhookId: "your-webhook-id",
};

// Example 3: Process intersection of rows and columns
const processIntersection = {
  rowIds: ["row_1", "row_2"], // Specific rows
  columnIds: ["col_product_name", "col_category"], // Specific columns
  processOnlyEmpty: true, // Only process empty cells in the intersection
  webhookId: "your-webhook-id",
};

const response = await fetch(
  `https://secure-api.getclaro.ai/api/v2/datasets/${datasetId}/tasks/bulk`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(processAllEmpty), // Use any of the examples above
  }
);

{
  "taskId": "task_550e8400-e29b-41d4-a716-446655440000",
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "bulk_processing",
  "status": "queued",
  "targetCells": 150,
  "processOnlyEmpty": true,
  "estimatedDuration": "3-7 minutes",
  "createdAt": "2024-03-14T15:30:00Z",
  "webhookId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

{
  "error": "Invalid cell selection",
  "code": "INVALID_SELECTION",
  "details": {
    "message": "Cannot combine cellIds with rowIds or columnIds. Use either cellIds alone, or rowIds/columnIds, or no IDs to process all empty cells"
  }
}

Get Task Status

Retrieve detailed information about a specific task and its progress.

curl -X GET "https://secure-api.getclaro.ai/api/v2/datasets/$DATASET_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

dataset_id = "your-dataset-id"  # Replace with your dataset ID
task_id = "your-task-id"  # Replace with your task ID

response = requests.get(
    f"https://secure-api.getclaro.ai/api/v2/datasets/{dataset_id}/tasks/{task_id}",
    headers=headers
)

const datasetId = "your-dataset-id"; // Replace with your dataset ID
const taskId = "your-task-id"; // Replace with your task ID

const response = await fetch(
  `https://secure-api.getclaro.ai/api/v2/datasets/${datasetId}/tasks/${taskId}`,
  {
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);

{
  "taskId": "task_550e8400-e29b-41d4-a716-446655440000",
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "bulk_processing",
  "status": "processing",
  "progress": {
    "completed": 75,
    "total": 150,
    "percentage": 50
  },
  "targetCells": 150,
  "processOnlyEmpty": true,
  "estimatedCompletion": "2024-03-14T15:37:00Z",
  "createdAt": "2024-03-14T15:30:00Z",
  "startedAt": "2024-03-14T15:31:00Z",
  "webhookId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

{
  "taskId": "task_550e8400-e29b-41d4-a716-446655440000",
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "new_rows",
  "status": "completed",
  "progress": {
    "completed": 100,
    "total": 100,
    "percentage": 100
  },
  "rowCount": 100,
  "results": {
    "processedCells": 500,
    "successfulCells": 485,
    "failedCells": 15,
    "newRowsCreated": 100
  },
  "createdAt": "2024-03-14T15:30:00Z",
  "startedAt": "2024-03-14T15:31:00Z",
  "completedAt": "2024-03-14T15:38:00Z",
  "webhookId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

{
  "error": "Task not found",
  "code": "TASK_NOT_FOUND",
  "details": {
    "taskId": "task_invalid-id"
  }
}

Cancel Task

Cancel a running or queued task. Only tasks in queued or processing status can be cancelled.

curl -X DELETE "https://secure-api.getclaro.ai/api/v2/datasets/$DATASET_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

dataset_id = "your-dataset-id"  # Replace with your dataset ID
task_id = "your-task-id"  # Replace with your task ID

response = requests.delete(
    f"https://secure-api.getclaro.ai/api/v2/datasets/{dataset_id}/tasks/{task_id}",
    headers=headers
)

const datasetId = "your-dataset-id"; // Replace with your dataset ID
const taskId = "your-task-id"; // Replace with your task ID

const response = await fetch(
  `https://secure-api.getclaro.ai/api/v2/datasets/${datasetId}/tasks/${taskId}`,
  {
    method: "DELETE",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
);

{
  "message": "Task cancelled successfully",
  "taskId": "task_550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "cancelledAt": "2024-03-14T15:35:00Z"
}

{
  "error": "Cannot cancel task",
  "code": "TASK_NOT_CANCELLABLE",
  "details": {
    "message": "Task is already completed or failed",
    "currentStatus": "completed"
  }
}

Task Types and Operations

Data Enrichment Tasks

Enhance existing data with additional attributes and classifications.

New Rows: Generate new rows with enriched data based on dataset patterns
Bulk Processing: Enrich specific cells, columns, or rows with missing attributes

Data Extraction Tasks

Extract structured data from unstructured sources.

New Rows: Process new documents and extract structured data
Bulk Processing: Re-extract data from specific cells or update extraction results

Map Extraction Tasks

Extract location-based data within geographic boundaries.

New Rows: Find new locations within specified map boundaries
Bulk Processing: Update location data for specific entries

AI Generation Tasks

Generate synthetic data using AI models.

New Rows: Create new synthetic rows based on existing dataset patterns
Bulk Processing: Generate content for specific empty cells

Request Parameters

Create New Rows Task

Parameter	Type	Required	Description
`rowCount`	number	Yes	Number of new rows to generate (max: 10000)
`webhookId`	string	No	Webhook ID for completion notification

Create Bulk Processing Task

Parameter	Type	Required	Description
`cellIds`	array	No	Array of specific cell IDs to process
`columnIds`	array	No	Array of column IDs to process
`rowIds`	array	No	Array of row IDs to process
`processOnlyEmpty`	boolean	No	Only process empty cells (default: true)
`webhookId`	string	No	Webhook ID for completion notification

Bulk Processing Logic

Target Selection Options:

Process All Empty Cells: Omit all ID parameters to process all empty cells in the dataset
Specific Cells: Use cellIds to target exact cells (cannot combine with row/column IDs)
Entire Columns: Use columnIds to process all cells in specified columns
Entire Rows: Use rowIds to process all cells in specified rows
Row-Column Intersection: Use both rowIds and columnIds to process only cells at their intersection

Examples:

// Process all empty cells in dataset
{}

// Process specific cells only
{"cellIds": ["cell_1", "cell_2"]}

// Process entire columns
{"columnIds": ["col_name", "col_category"]}

// Process entire rows
{"rowIds": ["row_1", "row_2"]}

// Process intersection: only cells where specified rows and columns meet
{"rowIds": ["row_1", "row_2"], "columnIds": ["col_name", "col_category"]}

Task Status Values

Status	Description
`queued`	Task is waiting to be processed
`processing`	Task is currently being executed
`completed`	Task finished successfully
`failed`	Task encountered an error and stopped
`cancelled`	Task was cancelled by user request

Dataset Locking

Datasets are automatically locked when a task is created and remain locked until the task completes, fails, or is cancelled. During this time:

No new tasks can be created on the dataset
Dataset structure cannot be modified
Data cannot be manually edited
Other operations may be restricted

Webhook Notifications

When a webhookId is provided, the system will send HTTP POST notifications to the configured webhook URL upon task completion:

{
  "taskId": "task_550e8400-e29b-41d4-a716-446655440000",
  "datasetId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "type": "new_rows",
  "completedAt": "2024-03-14T15:38:00Z",
  "results": {
    "processedCells": 500,
    "successfulCells": 485,
    "failedCells": 15,
    "newRowsCreated": 100
  }
}

Error Codes

Code	Description
`DATASET_LOCKED`	Dataset is locked by another task
`DATASET_NOT_FOUND`	Dataset doesn’t exist
`TASK_NOT_FOUND`	Task doesn’t exist
`TASK_NOT_CANCELLABLE`	Task cannot be cancelled in current state
`INVALID_SELECTION`	Invalid cell/column/row selection
`QUOTA_EXCEEDED`	Task creation limit reached
`WEBHOOK_NOT_FOUND`	Specified webhook doesn’t exist

Create New Rows Task

Create Bulk Processing Task

Get Task Status

Cancel Task

Task Types and Operations

Data Enrichment Tasks

Data Extraction Tasks

Map Extraction Tasks

AI Generation Tasks

Request Parameters

Create New Rows Task

Create Bulk Processing Task

Bulk Processing Logic

Target Selection Options:

Examples:

Task Status Values

Dataset Locking

Webhook Notifications

Error Codes

Next Steps

Manage Datasets

Manage Webhooks

​Create New Rows Task

​Create Bulk Processing Task

​Get Task Status

​Cancel Task

​Task Types and Operations

​Data Enrichment Tasks

​Data Extraction Tasks

​Map Extraction Tasks

​AI Generation Tasks

​Request Parameters

​Create New Rows Task

​Create Bulk Processing Task

​Bulk Processing Logic

​Target Selection Options:

​Examples:

​Task Status Values

​Dataset Locking

​Webhook Notifications

​Error Codes

​Next Steps

Manage Datasets

Manage Webhooks

Create New Rows Task

Create Bulk Processing Task

Get Task Status

Cancel Task

Task Types and Operations

Data Enrichment Tasks

Data Extraction Tasks

Map Extraction Tasks

AI Generation Tasks

Request Parameters

Create New Rows Task

Create Bulk Processing Task

Bulk Processing Logic

Target Selection Options:

Examples:

Task Status Values

Dataset Locking

Webhook Notifications

Error Codes

Next Steps