Skip to main content
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"
  }'

​
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"
}'

​
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"

​
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"

​
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

ParameterTypeRequiredDescription
rowCountnumberYesNumber of new rows to generate (max: 10000)
webhookIdstringNoWebhook ID for completion notification

​
Create Bulk Processing Task

ParameterTypeRequiredDescription
cellIdsarrayNoArray of specific cell IDs to process
columnIdsarrayNoArray of column IDs to process
rowIdsarrayNoArray of row IDs to process
processOnlyEmptybooleanNoOnly process empty cells (default: true)
webhookIdstringNoWebhook ID for completion notification

​
Bulk Processing Logic

​
Target Selection Options:

  1. Process All Empty Cells: Omit all ID parameters to process all empty cells in the dataset
  2. Specific Cells: Use cellIds to target exact cells (cannot combine with row/column IDs)
  3. Entire Columns: Use columnIds to process all cells in specified columns
  4. Entire Rows: Use rowIds to process all cells in specified rows
  5. 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

StatusDescription
queuedTask is waiting to be processed
processingTask is currently being executed
completedTask finished successfully
failedTask encountered an error and stopped
cancelledTask 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

CodeDescription
DATASET_LOCKEDDataset is locked by another task
DATASET_NOT_FOUNDDataset doesn’t exist
TASK_NOT_FOUNDTask doesn’t exist
TASK_NOT_CANCELLABLETask cannot be cancelled in current state
INVALID_SELECTIONInvalid cell/column/row selection
QUOTA_EXCEEDEDTask creation limit reached
WEBHOOK_NOT_FOUNDSpecified webhook doesn’t exist

​
Next Steps

Manage Datasets

View and manage your dataset structure and data

Manage Webhooks

Set up webhooks for task completion notifications