Tasks Api

Tasks API - Running and Monitoring

Learn how to trigger, monitor, and manage Tadabase tasks programmatically via the REST API.

What are Tasks?

Tasks in Tadabase are automated workflows that run on schedules or can be triggered via API. They can send emails, update records, call webhooks, and perform other actions across multiple records.

List All Tasks

Get all tasks configured in your application:

GET /api/v1/tasks

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "total_tasks": 3,
  "tasks": [
    {
      "task_id": "task_abc123",
      "name": "Daily Email Report",
      "status": "Active",
      "data_table_id": "lGArg7rmR6",
      "occurrence": "Daily",
      "next_run_at": "2024-01-28 10:00:00",
      "type": "Schedule"
    },
    {
      "task_id": "task_def456",
      "name": "Update Customer Status",
      "status": "Active",
      "data_table_id": "mH8s2pQtS9",
      "occurrence": "Weekly",
      "next_run_at": "2024-01-29 14:00:00",
      "type": "Schedule"
    }
  ]
}

Task Properties

Property	Description
`task_id`	Unique task identifier
`name`	Task name
`status`	Active or Inactive
`data_table_id`	Table the task operates on
`occurrence`	Schedule (Daily, Weekly, Monthly, etc.)
`next_run_at`	Next scheduled execution time
`type`	Type of task (Schedule, API, etc.)

Run a Task

Trigger immediate execution of a task:

POST /api/v1/tasks/run/{taskId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "task_queue_id": "queue_xyz789",
  "msg": "Task started successfully"
}

The task_queue_id is used to monitor the task's progress.

API Key Permission Required

Your API key must have the allow_task permission enabled to run tasks.

Check Task Status

Monitor the progress of task executions.

All Active Tasks

GET /api/v1/tasks/status

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Specific Task Queue

GET /api/v1/tasks/status/queue/{taskQueueId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

All Executions of a Specific Task

GET /api/v1/tasks/status/task/{taskId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Status Response

{
  "type": "success",
  "total_tasks": 1,
  "tasks": [
    {
      "task_queue_id": "queue_xyz789",
      "task_id": "task_abc123",
      "total_records": 500,
      "total_record_proceed": 450,
      "start_at": "2024-01-27 10:00:00",
      "run_type": "API",
      "status": "start"
    }
  ]
}

Status Values

Status	Description
`start`	Task is running
`complete`	Task completed successfully
`failed`	Task failed with errors
`terminated`	Task was manually terminated

Task History

Get completed task executions:

GET /api/v1/tasks/history

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "total_tasks": 50,
  "tasks": [
    {
      "task_queue_id": "queue_abc123",
      "task_id": "task_abc123",
      "task_name": "Daily Email Report",
      "total_records": 100,
      "total_record_proceed": 100,
      "start_at": "2024-01-27 10:00:00",
      "end_at": "2024-01-27 10:05:30",
      "run_type": "Schedule",
      "status": "complete"
    }
  ]
}

Terminate a Running Task

Terminate Specific Execution

POST /api/v1/tasks/terminate/queue/{taskQueueId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Terminate All Executions of a Task

POST /api/v1/tasks/terminate/task/{taskId}

Headers:
  X-Tadabase-App-id: your_app_id
  X-Tadabase-App-Key: your_app_key
  X-Tadabase-App-Secret: your_app_secret

Response

{
  "type": "success",
  "msg": "Task terminated successfully"
}

Monitoring Task Progress

async function runAndMonitorTask(taskId) {
  // Start task
  const runResponse = await fetch(
    `https://api.tadabase.io/api/v1/tasks/run/${taskId}`,
    {
      method: 'POST',
      headers: {
        'X-Tadabase-App-id': 'your_app_id',
        'X-Tadabase-App-Key': 'your_app_key',
        'X-Tadabase-App-Secret': 'your_app_secret'
      }
    }
  );

  const runData = await runResponse.json();
  const queueId = runData.task_queue_id;

  console.log(`Task started. Queue ID: ${queueId}`);

  // Poll for status
  let status = 'start';
  while (status === 'start') {
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds

    const statusResponse = await fetch(
      `https://api.tadabase.io/api/v1/tasks/status/queue/${queueId}`,
      { headers }
    );

    const statusData = await statusResponse.json();

    if (statusData.tasks && statusData.tasks.length > 0) {
      const task = statusData.tasks[0];
      status = task.status;

      console.log(
        `Progress: ${task.total_record_proceed}/${task.total_records} records (${Math.round((task.total_record_proceed/task.total_records)*100)}%)`
      );
    }
  }

  console.log(`Task completed with status: ${status}`);
  return status;
}

// Usage
await runAndMonitorTask('task_abc123');

Task Execution Patterns

1. Run and Forget

// Just trigger the task, don't wait for completion
async function triggerTask(taskId) {
  const response = await fetch(
    `https://api.tadabase.io/api/v1/tasks/run/${taskId}`,
    {
      method: 'POST',
      headers
    }
  );

  const data = await response.json();
  console.log(`Task ${taskId} started with queue ID: ${data.task_queue_id}`);
  return data.task_queue_id;
}

2. Run and Wait for Completion

async function runTaskAndWait(taskId, maxWaitMinutes = 30) {
  const response = await fetch(
    `https://api.tadabase.io/api/v1/tasks/run/${taskId}`,
    {
      method: 'POST',
      headers
    }
  );

  const runData = await response.json();
  const queueId = runData.task_queue_id;
  const maxWaitTime = maxWaitMinutes * 60 * 1000;
  const startTime = Date.now();

  while (Date.now() - startTime  setTimeout(resolve, 5000));

    const statusResponse = await fetch(
      `https://api.tadabase.io/api/v1/tasks/status/queue/${queueId}`,
      { headers }
    );

    const statusData = await statusResponse.json();

    if (statusData.tasks && statusData.tasks.length > 0) {
      const task = statusData.tasks[0];

      if (task.status === 'complete') {
        return { success: true, task };
      } else if (task.status === 'failed') {
        return { success: false, error: 'Task failed', task };
      } else if (task.status === 'terminated') {
        return { success: false, error: 'Task was terminated', task };
      }
    }
  }

  return { success: false, error: 'Timeout waiting for task completion' };
}

// Usage
const result = await runTaskAndWait('task_abc123', 10);
if (result.success) {
  console.log('Task completed successfully');
} else {
  console.error('Task failed:', result.error);
}

3. Run with Progress Callback

async function runTaskWithProgress(taskId, onProgress) {
  const response = await fetch(
    `https://api.tadabase.io/api/v1/tasks/run/${taskId}`,
    {
      method: 'POST',
      headers
    }
  );

  const runData = await response.json();
  const queueId = runData.task_queue_id;
  let status = 'start';

  while (status === 'start') {
    await new Promise(resolve => setTimeout(resolve, 5000));

    const statusResponse = await fetch(
      `https://api.tadabase.io/api/v1/tasks/status/queue/${queueId}`,
      { headers }
    );

    const statusData = await statusResponse.json();

    if (statusData.tasks && statusData.tasks.length > 0) {
      const task = statusData.tasks[0];
      status = task.status;

      if (onProgress && task.total_records > 0) {
        onProgress({
          queueId: queueId,
          processed: task.total_record_proceed,
          total: task.total_records,
          percentage: Math.round((task.total_record_proceed / task.total_records) * 100),
          status: task.status
        });
      }
    }
  }

  return status;
}

// Usage
await runTaskWithProgress('task_abc123', (progress) => {
  console.log(`Task progress: ${progress.percentage}% (${progress.processed}/${progress.total})`);
});

4. Run Multiple Tasks in Sequence

async function runTaskSequence(taskIds) {
  const results = [];

  for (const taskId of taskIds) {
    console.log(`Starting task: ${taskId}`);

    const result = await runTaskAndWait(taskId);
    results.push({
      taskId,
      ...result
    });

    if (!result.success) {
      console.error(`Task ${taskId} failed. Stopping sequence.`);
      break;
    }

    console.log(`Task ${taskId} completed successfully`);
  }

  return results;
}

// Usage
const results = await runTaskSequence([
  'task_1_data_cleanup',
  'task_2_send_emails',
  'task_3_generate_reports'
]);

console.log('Sequence complete:', results);

5. Run Multiple Tasks in Parallel

async function runTasksParallel(taskIds) {
  const promises = taskIds.map(taskId =>
    fetch(
      `https://api.tadabase.io/api/v1/tasks/run/${taskId}`,
      {
        method: 'POST',
        headers
      }
    ).then(r => r.json())
  );

  const results = await Promise.all(promises);

  return results.map((result, index) => ({
    taskId: taskIds[index],
    queueId: result.task_queue_id
  }));
}

// Usage
const started = await runTasksParallel([
  'task_1',
  'task_2',
  'task_3'
]);

console.log('All tasks started:', started);

Error Handling

async function runTaskSafely(taskId) {
  try {
    // Check if task exists
    const tasksResponse = await fetch(
      'https://api.tadabase.io/api/v1/tasks',
      { headers }
    );

    const tasksData = await tasksResponse.json();
    const task = tasksData.tasks.find(t => t.task_id === taskId);

    if (!task) {
      throw new Error(`Task ${taskId} not found`);
    }

    if (task.status !== 'Active') {
      throw new Error(`Task ${taskId} is not active`);
    }

    // Run task
    const runResponse = await fetch(
      `https://api.tadabase.io/api/v1/tasks/run/${taskId}`,
      {
        method: 'POST',
        headers
      }
    );

    const runData = await runResponse.json();

    if (runData.type === 'error') {
      throw new Error(`Failed to start task: ${runData.msg}`);
    }

    console.log(`Task started successfully. Queue ID: ${runData.task_queue_id}`);
    return runData.task_queue_id;

  } catch (error) {
    console.error('Task execution error:', error.message);
    throw error;
  }
}

Best Practices

Check task status before running: Ensure task is Active
Don't poll too frequently: Wait at least 5 seconds between status checks
Set timeouts: Don't wait indefinitely for task completion
Handle failures gracefully: Task may fail for various reasons
Log queue IDs: Save queue IDs for tracking and debugging
Monitor long-running tasks: Check progress for tasks processing many records
Use sequential execution: For dependent tasks, run in sequence
Rate limit consideration: Running tasks counts toward API rate limits

Common Use Cases

Scheduled Data Processing

// Trigger nightly data processing task
async function runNightlyProcessing() {
  const taskId = 'task_nightly_processing';

  console.log('Starting nightly processing...');

  const result = await runTaskAndWait(taskId, 60); // Wait up to 1 hour

  if (result.success) {
    console.log(`Processed ${result.task.total_record_proceed} records`);
    // Send success notification
    await sendNotification('Nightly processing completed successfully');
  } else {
    console.error('Nightly processing failed');
    // Send alert
    await sendAlert('Nightly processing failed!');
  }
}

On-Demand Email Campaigns

// Trigger email campaign and monitor progress
async function launchEmailCampaign(taskId) {
  console.log('Launching email campaign...');

  await runTaskWithProgress(taskId, (progress) => {
    console.log(`Sent ${progress.processed}/${progress.total} emails (${progress.percentage}%)`);

    // Update UI
    updateProgressBar(progress.percentage);
  });

  console.log('Email campaign completed');
}

Data Synchronization

// Run sync tasks in sequence
async function syncData() {
  const syncTasks = [
    'task_sync_customers',
    'task_sync_orders',
    'task_sync_products'
  ];

  for (const taskId of syncTasks) {
    console.log(`Syncing: ${taskId}...`);

    const result = await runTaskAndWait(taskId, 30);

    if (!result.success) {
      console.error(`Sync failed at ${taskId}`);
      return false;
    }
  }

  console.log('All data synchronized');
  return true;
}

Next Steps

Learn how to work with automations via the API:

→ Automations API

Discover how to trigger and monitor automated workflows.

How did we do ?

Batch Operations

Formulas And Equations

Tasks Api

Tasks API - Running and Monitoring

What are Tasks?

List All Tasks

Response

Task Properties

Run a Task

Response

API Key Permission Required

Check Task Status

All Active Tasks

Specific Task Queue

All Executions of a Specific Task

Status Response

Status Values

Task History

Response

Terminate a Running Task

Terminate Specific Execution

Terminate All Executions of a Task

Response

Monitoring Task Progress

Task Execution Patterns

1. Run and Forget

2. Run and Wait for Completion

3. Run with Progress Callback

4. Run Multiple Tasks in Sequence

5. Run Multiple Tasks in Parallel

Error Handling

Best Practices

Common Use Cases

Scheduled Data Processing

On-Demand Email Campaigns

Data Synchronization

Next Steps

How did we do ?

We'd love to hear your feedback.