> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vambe.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Get tasks

> Retrieves all tasks based on query parameters. Filters can include responsible user IDs and date range (fromDate/toDate).

## 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

```bash theme={null}
curl -X GET 'https://api.vambe.me/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

```json theme={null}
[
  {
    "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

```javascript theme={null}
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.me/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

```javascript theme={null}
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.me/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

```javascript theme={null}
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.me/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

```javascript theme={null}
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.me/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

```javascript theme={null}
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.me/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

```javascript theme={null}
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.me/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

```javascript theme={null}
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.me/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

## Related Endpoints

* [POST /api/public/tasks](/reference/tasks/create-task) - Create a new task
* [PUT /api/public/tasks/{id}](/reference/tasks/update-task) - Update an existing task
* [DELETE /api/public/tasks/{id}](/reference/tasks/delete-task) - Delete a task
* [GET /api/public/team-members/all](/reference/team-members/get-all-team-members) - 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


## OpenAPI

````yaml get /api/public/tasks
openapi: 3.0.0
info:
  title: Vambe AI API
  description: Vambe AI documentation
  version: '1.0'
  contact: {}
servers:
  - url: https://api.vambe.me
    description: Production Server
security: []
tags:
  - name: Vambe AI
    description: ''
paths:
  /api/public/tasks:
    get:
      tags:
        - tasks
      summary: Get tasks
      description: >-
        Retrieves all tasks based on query parameters. Filters can include
        responsible user IDs and date range (fromDate/toDate).
      operationId: TaskPublicController_getTasks
      parameters:
        - name: responsibleIds
          required: false
          in: query
          description: Responsible user IDs to filter tasks
          schema:
            type: array
            items:
              type: string
        - name: fromDate
          required: true
          in: query
          schema:
            type: string
        - name: toDate
          required: true
          in: query
          schema:
            type: string
        - name: includeTasksWithoutDates
          required: false
          in: query
          schema:
            default: true
            type: boolean
        - name: searchFilter
          required: false
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Returns an array of tasks matching the query criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaskResponseDto'
        '400':
          description: Invalid query parameters
        '401':
          description: Unauthorized - Invalid or missing authentication token
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponseDto'
components:
  schemas:
    TaskResponseDto:
      type: object
      properties: {}

````