Get tasks - Welcome 👋

Overview

Retrieve a list of tasks based on filters such as responsible users and date range. This endpoint allows you to fetch tasks assigned to specific team members within a specified time period. Use this endpoint to build task management interfaces, dashboards, or integrate task data with external systems.

Use Cases

Task Dashboard: Display tasks for specific team members or the entire team
Calendar Views: Show tasks by date range for calendar interfaces
Team Management: Monitor task assignments and deadlines
Reporting & Analytics: Generate task completion reports by team member
Integration: Sync tasks with external project management tools
Mobile Apps: Fetch tasks for mobile task management applications

Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

x-api-key: your_api_key_here

Query Parameters

Parameter	Type	Required	Default	Description
`responsibleIds`	string[]	Yes	-	Array of user IDs to filter tasks by responsible team members. Can be empty array for all users.
`fromDate`	string	Yes	-	Start date for filtering tasks (ISO 8601 format: YYYY-MM-DD)
`toDate`	string	Yes	-	End date for filtering tasks (ISO 8601 format: YYYY-MM-DD)
`includeTasksWithoutDates`	boolean	No	`true`	Whether to include tasks that don’t have a due date in the results

Response Structure

The endpoint returns an array of task objects:

Task Object

Field	Type	Description
`id`	string (UUID)	Unique identifier for the task
`title`	string	Task title
`description`	string	Detailed description of the task
`due_timezone`	string \| null	Timezone for the due date (e.g., “America/Santiago”)
`due_at`	string \| null	Due date and time (ISO 8601 format)
`is_all_day`	boolean	Whether the task is an all-day task
`created_at`	string	Task creation date (ISO 8601 format)
`ai_contact_id`	string \| null	Associated contact ID if applicable
`ai_customer_id`	string \| null	Associated customer ID if applicable
`task_status_config_id`	string (UUID)	ID of the status configuration
`priority`	string	Task priority: “low”, “medium”, or “high”
`creator_id`	string (UUID)	ID of the user who created the task
`task_responsibles`	array	Array of responsible user objects
`status_config`	object \| null	Custom status configuration object

Task Responsible Object

Field	Type	Description
`responsible_id`	string (UUID)	ID of the responsible user

Status Config Object

Field	Type	Description
`id`	string (UUID)	Status configuration ID
`name`	string	Display name for the status
`color`	string	Hex color code for the status (e.g., “#60a5fa”)
`type`	string	Status type: “initial”, “in_progress”, “done”, or “master_done”
`order`	number	Display order for status (lower numbers appear first)

Example Request

curl -X GET 'https://api.vambe.ai/api/public/tasks?responsibleIds[]=228d7a0d-9072-4ca8-939b-959b75cc606a&fromDate=2025-10-01&toDate=2025-10-31&includeTasksWithoutDates=true' \
  -H 'x-api-key: your_api_key_here'

Example Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Follow up with customer",
    "description": "Call customer regarding their inquiry about pricing",
    "due_timezone": "America/Santiago",
    "due_at": "2025-10-25T14:00:00.000Z",
    "is_all_day": false,
    "created_at": "2025-10-20T10:30:00.000Z",
    "ai_contact_id": "contact-uuid-123",
    "ai_customer_id": null,
    "task_status_config_id": "status-uuid-789",
    "priority": "high",
    "creator_id": "user-uuid-456",
    "task_responsibles": [
      {
        "responsible_id": "228d7a0d-9072-4ca8-939b-959b75cc606a"
      }
    ],
    "status_config": {
      "id": "status-uuid-789",
      "name": "Pendiente",
      "color": "#60a5fa",
      "type": "initial",
      "order": 1
    }
  },
  {
    "id": "223e4567-e89b-12d3-a456-426614174001",
    "title": "Prepare quarterly report",
    "description": "Compile Q3 sales data and prepare presentation",
    "due_timezone": "America/Santiago",
    "due_at": "2025-10-28T00:00:00.000Z",
    "is_all_day": true,
    "created_at": "2025-10-15T09:00:00.000Z",
    "ai_contact_id": null,
    "ai_customer_id": null,
    "task_status_config_id": "status-uuid-789",
    "priority": "medium",
    "creator_id": "user-uuid-456",
    "task_responsibles": [
      {
        "responsible_id": "228d7a0d-9072-4ca8-939b-959b75cc606a"
      }
    ],
    "status_config": {
      "id": "status-uuid-789",
      "name": "Pendiente",
      "color": "#60a5fa",
      "type": "initial",
      "order": 1
    }
  }
]

Common Use Cases

1. Fetch Tasks for a Team Member

const getTasksForAgent = async (agentId, startDate, endDate) => {
  const params = new URLSearchParams();
  params.append('responsibleIds[]', agentId);
  params.append('fromDate', startDate);
  params.append('toDate', endDate);

  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks?${params.toString()}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const tasks = await response.json();
  return tasks;
};

// Example usage
const tasks = await getTasksForAgent(
  '228d7a0d-9072-4ca8-939b-959b75cc606a',
  '2025-10-01',
  '2025-10-31',
);
console.log(`Found ${tasks.length} tasks`);

2. Fetch Tasks for Multiple Team Members

const getTasksForTeam = async (agentIds, startDate, endDate) => {
  const params = new URLSearchParams();
  agentIds.forEach((id) => params.append('responsibleIds[]', id));
  params.append('fromDate', startDate);
  params.append('toDate', endDate);

  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks?${params.toString()}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  return await response.json();
};

// Example usage
const teamTasks = await getTasksForTeam(
  ['agent-1-uuid', 'agent-2-uuid', 'agent-3-uuid'],
  '2025-10-01',
  '2025-10-31',
);

3. Filter Overdue Tasks

const getOverdueTasks = async (agentId, startDate, endDate) => {
  const params = new URLSearchParams();
  params.append('responsibleIds[]', agentId);
  params.append('fromDate', startDate);
  params.append('toDate', endDate);

  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks?${params.toString()}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const tasks = await response.json();
  const now = new Date();

  // Filter overdue tasks (tasks with due dates in the past and not in a "done" status)
  const overdueTasks = tasks.filter((task) => {
    if (!task.due_at) return false;
    // Check if status is done based on status_config type
    const isDone =
      task.status_config?.type === 'done' ||
      task.status_config?.type === 'master_done';
    if (isDone) return false;
    return new Date(task.due_at) < now;
  });

  return overdueTasks;
};

4. Group Tasks by Priority

const getTasksGroupedByPriority = async (agentId, startDate, endDate) => {
  const params = new URLSearchParams();
  params.append('responsibleIds[]', agentId);
  params.append('fromDate', startDate);
  params.append('toDate', endDate);

  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks?${params.toString()}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const tasks = await response.json();

  // Group by priority
  const grouped = {
    high: tasks.filter((t) => t.priority === 'high'),
    medium: tasks.filter((t) => t.priority === 'medium'),
    low: tasks.filter((t) => t.priority === 'low'),
  };

  return grouped;
};

5. Build Task Calendar View

const getTasksForCalendar = async (agentId, startDate, endDate) => {
  const params = new URLSearchParams();
  params.append('responsibleIds[]', agentId);
  params.append('fromDate', startDate);
  params.append('toDate', endDate);

  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks?${params.toString()}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const tasks = await response.json();

  // Format for calendar component
  const calendarEvents = tasks.map((task) => ({
    id: task.id,
    title: task.title,
    start: task.due_at,
    allDay: task.is_all_day,
    backgroundColor: task.status_config?.color || '#3788d8',
    extendedProps: {
      description: task.description,
      priority: task.priority,
      statusType: task.status_config?.type,
      statusName: task.status_config?.name,
      contactId: task.ai_contact_id,
    },
  }));

  return calendarEvents;
};

6. Calculate Task Completion Rate

const getTaskCompletionRate = async (agentId, startDate, endDate) => {
  const params = new URLSearchParams();
  params.append('responsibleIds[]', agentId);
  params.append('fromDate', startDate);
  params.append('toDate', endDate);

  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks?${params.toString()}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const tasks = await response.json();

  const completedTasks = tasks.filter(
    (t) =>
      t.status_config?.type === 'done' ||
      t.status_config?.type === 'master_done',
  ).length;
  const totalTasks = tasks.length;
  const completionRate =
    totalTasks > 0 ? (completedTasks / totalTasks) * 100 : 0;

  return {
    totalTasks,
    completedTasks,
    openTasks: totalTasks - completedTasks,
    completionRate: completionRate.toFixed(2) + '%',
  };
};

7. Include or Exclude Tasks Without Due Dates

const getTasksWithOrWithoutDates = async (
  agentId,
  startDate,
  endDate,
  includeTasksWithoutDates = true,
) => {
  const params = new URLSearchParams();
  params.append('responsibleIds[]', agentId);
  params.append('fromDate', startDate);
  params.append('toDate', endDate);
  params.append('includeTasksWithoutDates', includeTasksWithoutDates);

  const response = await fetch(
    `https://api.vambe.ai/api/public/tasks?${params.toString()}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const tasks = await response.json();

  // Separate tasks with and without dates
  const tasksWithDates = tasks.filter((t) => t.due_at !== null);
  const tasksWithoutDates = tasks.filter((t) => t.due_at === null);

  return {
    tasksWithDates,
    tasksWithoutDates,
    total: tasks.length,
  };
};

// Example: Get only tasks with due dates
const tasksWithDatesOnly = await getTasksWithOrWithoutDates(
  'agent-uuid',
  '2025-10-01',
  '2025-10-31',
  false, // Exclude tasks without dates
);

Response Characteristics

Array Format: Always returns an array, even if empty
Date Format: All dates are in ISO 8601 format
Timezone Awareness: Tasks include timezone information for accurate due date handling
Filtered by Organization: Only returns tasks from your organization
Sorted: Tasks are ordered by priority (high to low), then by ID
Tasks Without Dates: By default, tasks without due dates are included when includeTasksWithoutDates=true (default)

Error Responses

Status Code	Description
400	Bad Request - Invalid query parameters or date format
401	Unauthorized - Invalid or missing API key
500	Internal Server Error - Something went wrong

Performance Tips

Date Range: Use reasonable date ranges to avoid performance issues
Multiple Agents: Fetching tasks for multiple agents at once is more efficient than individual requests
Client-side Filtering: Consider fetching a broader date range and filtering on the client
Pagination: For large result sets, consider implementing date-based pagination
Caching: Cache results for a few minutes to reduce API calls

POST /api/public/tasks - Create a new task
PUT /api/public/tasks/ - Update an existing task
DELETE /api/public/tasks/ - Delete a task
GET /api/public/team-members/all - Get team members for responsibleIds

Notes

Required Parameters: responsibleIds, fromDate, and toDate are required query parameters
Optional Parameters: includeTasksWithoutDates is optional and defaults to true
Date Format: Use YYYY-MM-DD format for dates (e.g., “2025-10-01”)
Array Parameters: responsibleIds is an array and should be passed as responsibleIds[]=uuid1&responsibleIds[]=uuid2. An empty array will return tasks for all team members
Time Boundaries: fromDate starts at 00:00:00 and toDate ends at 23:59:59 in the server timezone
Status Config: Tasks use custom status configurations (status_config) instead of simple “open/done” status. Check the status_config.type field for status information
Tasks Without Dates: When includeTasksWithoutDates=true, tasks without due dates are included regardless of the date range filter

Query Parameters

responsibleIds

any[]

required

fromDate

string

required

toDate

string

required

includeTasksWithoutDates

boolean

default:true

Response

Returns an array of tasks matching the query criteria

The response is of type object[].

Task Management

​Overview

​Use Cases

​Authentication

​Query Parameters

​Response Structure

​Task Object

​Task Responsible Object

​Status Config Object

​Example Request

​Example Response

​Common Use Cases

​1. Fetch Tasks for a Team Member

​2. Fetch Tasks for Multiple Team Members

​3. Filter Overdue Tasks

​4. Group Tasks by Priority

​5. Build Task Calendar View

​6. Calculate Task Completion Rate

​7. Include or Exclude Tasks Without Due Dates

​Response Characteristics

​Error Responses

​Performance Tips

​Related Endpoints

​Notes

Query Parameters

Response

Overview

Use Cases

Authentication

Query Parameters

Response Structure

Task Object

Task Responsible Object

Status Config Object

Example Request

Example Response

Common Use Cases

1. Fetch Tasks for a Team Member

2. Fetch Tasks for Multiple Team Members

3. Filter Overdue Tasks

4. Group Tasks by Priority

5. Build Task Calendar View

6. Calculate Task Completion Rate

7. Include or Exclude Tasks Without Due Dates

Response Characteristics

Error Responses

Performance Tips

Related Endpoints

Notes