Get Tasks

This tool retrieves tasks from the database with comprehensive filtering, pagination, and sorting capabilities. The tool is primarily designed to work with lead_id as the main filter to get all tasks related to a specific lead.

Primary Usage

The most common usage pattern is to filter tasks by lead_id to get all tasks associated with a specific lead:


{
  "lead_id": "abcdef12-3456-7890-abcd-ef1234567890"
}

Input Schema


{
  // Primary Filter (Recommended)
  "lead_id": "string", // UUID - Get all tasks for a specific lead
  
  // Additional Entity Filters
  "user_id": "string", // Optional - Filter by assigned user
  "site_id": "string", // Optional - Filter by site
  "visitor_id": "string", // Optional - Filter by visitor
  "agent_id": "string", // Optional - Filter by agent
  "command_id": "string", // Optional - Filter by command
  
  // Property Filters
  "type": "string", // Optional - Filter by task type
  "status": "string", // Optional - Filter by status (active, inactive, archived)
  "stage": "string", // Optional - Filter by stage (pending, in_progress, review, completed, on_hold, cancelled)
  "priority": "string", // Optional - Filter by priority (low, medium, high, urgent)
  
  // Date Range Filters
  "due_date_from": "string", // Optional - Filter tasks due after this date (ISO format)
  "due_date_to": "string", // Optional - Filter tasks due before this date (ISO format)
  "scheduled_date_from": "string", // Optional - Filter tasks scheduled after this date (ISO format)
  "scheduled_date_to": "string", // Optional - Filter tasks scheduled before this date (ISO format)
  "created_date_from": "string", // Optional - Filter tasks created after this date (ISO format)
  "created_date_to": "string", // Optional - Filter tasks created before this date (ISO format)
  
  // Search and Sorting
  "search": "string", // Optional - Search in title and description
  "sort_by": "string", // Optional - Sort field (default: "created_at")
  "sort_order": "string", // Optional - Sort order: "asc" or "desc" (default: "desc")
  
  // Pagination
  "limit": "number", // Optional - Number of results to return (default: 50, max: 500)
  "offset": "number", // Optional - Number of results to skip (default: 0)
  
  // Inclusion Options
  "include_completed": "boolean", // Optional - Include completed tasks (default: true)
  "include_archived": "boolean" // Optional - Include archived tasks (default: false)
}

Output Schema


{
  "success": "boolean",
  "data": {
    "tasks": [
      {
        "id": "string",
        "serial_id": "string",
        "title": "string",
        "description": "string",
        "address": "string",
        "type": "string",
        "status": "string",
        "stage": "string",
        "priority": "string",
        "user_id": "string",
        "site_id": "string",
        "lead_id": "string",
        "due_date": "string",
        "scheduled_date": "string",
        "command_id": "string",
        "agent_id": "string",
        "metadata": "object",
        "created_at": "string",
        "updated_at": "string",
        "completion_date": "string",
        "assigned_user": {
          "id": "string",
          "name": "string",
          "email": "string"
        },
        "related_lead": {
          "id": "string",
          "name": "string",
          "email": "string",
          "company": "string"
        },
        "site": {
          "id": "string",
          "name": "string",
          "url": "string"
        },
        "task_categories": [
          {
            "id": "string",
            "name": "string",
            "description": "string",
            "created_at": "string"
          }
        ],
        "task_comments": [
          {
            "id": "string",
            "content": "string",
            "user_id": "string",
            "created_at": "string",
            "updated_at": "string",
            "user": {
              "id": "string",
              "name": "string",
              "email": "string"
            }
          }
        ]
      }
    ],
    "pagination": {
      "total": "number",
      "count": "number",
      "offset": "number",
      "limit": "number",
      "has_more": "boolean"
    },
    "filters_applied": "object",
    "summary": {
      "total_tasks": "number",
      "by_status": "object",
      "by_stage": "object",
      "by_priority": "object",
      "by_type": "object",
      "overdue_tasks": "number",
      "due_today": "number",
      "due_this_week": "number"
    }
  },
  "error": "string" // Only included if there was an error
}

Description

The Get Tasks tool provides comprehensive task retrieval functionality with advanced filtering, sorting, and analytics capabilities. The tool includes:

Flexible filtering by user, site, lead, dates, status, and more
Full-text search across task titles and descriptions
Relational data including user, lead, and site information
Task categories with detailed category information (name, description, color)
Task comments with complete comment history and user details
Pagination support for handling large datasets
Task analytics with summary statistics and counts
Date range filtering for time-based queries
Priority and status aggregations for dashboard views

Filtering Options

By Assignment and Ownership

user_id: Tasks assigned to specific users
site_id: Tasks belonging to specific sites
lead_id: Tasks related to specific leads
visitor_id: Tasks related to leads that originated from a specific visitor
agent_id: Tasks created by specific agents
command_id: Tasks generated by specific commands

By Status and Stage

type: Filter by task category (follow_up, marketing_campaign, etc.)
status: Filter by task status (active, inactive, archived)
stage: Filter by current stage (pending, in_progress, completed, etc.)
priority: Filter by priority level (low, medium, high, urgent)

By Date Ranges

due_date_from/to: Filter by due date range
scheduled_date_from/to: Filter by scheduled date range
created_date_from/to: Filter by creation date range

Advanced Options

search: Full-text search in title and description
include_completed: Include or exclude completed tasks
include_archived: Include or exclude archived tasks

Sorting Options

Sort Field	Description
`created_at`	Sort by creation date (default)
`updated_at`	Sort by last modification date
`due_date`	Sort by due date
`scheduled_date`	Sort by scheduled date
`priority`	Sort by priority level
`title`	Sort alphabetically by title
`type`	Sort by task type
`status`	Sort by task status

Task Categories and Comments

Task Categories

Each task can be assigned to one or more categories for better organization and filtering:

id: Unique identifier for the category
name: Display name of the category (e.g., “Marketing Campaign”, “Customer Support”)
description: Detailed description of what the category represents
created_at: When the category was created

Categories help organize tasks by business function, department, or project type, making it easier to filter and analyze task workloads.

Task Comments

Each task maintains a complete comment history for collaboration and tracking:

id: Unique identifier for the comment
content: The actual comment text/content
user_id: ID of the user who made the comment
created_at: When the comment was created
updated_at: When the comment was last modified
user: User information including name and email for context

Comments provide a chronological record of task progress, decisions made, and communication between team members.

Task Types (Suggested Examples)

Note: The type field accepts any string value. These are common examples, but custom task types are also supported.

Type	Description
`website_visit`	Website visit tracking tasks
`demo`	Product demonstration tasks
`meeting`	Meeting and appointment tasks
`email`	Email communication tasks
`call`	Phone call tasks
`quote`	Quote generation tasks
`contract`	Contract management tasks
`payment`	Payment processing tasks
`referral`	Referral tracking tasks
`feedback`	Feedback collection tasks
`follow_up`	General follow-up tasks
`support`	Customer support tasks
`custom_type`	Any custom task type

Task Stages (Customer Journey)

Stage	Description
`awareness`	Customer becomes aware of the product/service
`consideration`	Customer is considering the product/service
`decision`	Customer is making a decision about purchasing
`purchase`	Customer is in the purchasing process
`retention`	Customer has purchased and is being retained
`referral`	Customer is referring others to the product/service

Note: These are the standard customer journey stages, but custom stages can also be used as needed.

Task Status

Status	Description
`pending`	Task is created but not yet started
`in_progress`	Task is currently being worked on
`completed`	Task has been finished successfully
`failed`	Task has failed or encountered an error

Example Usage


// Example 1: Get all tasks for a specific lead (most common usage)
{
  "lead_id": "abcdef12-3456-7890-abcd-ef1234567890"
}
 
// Example 2: Get active tasks for a lead, sorted by priority
{
  "lead_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "status": "active",
  "sort_by": "priority",
  "sort_order": "desc"
}
 
// Example 3: Get pending tasks for a lead with pagination
{
  "lead_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "stage": "pending",
  "limit": 20,
  "offset": 0
}
 
// Example 4: Get recent tasks for a lead (exclude completed)
{
  "lead_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "include_completed": false,
  "sort_by": "created_at",
  "sort_order": "desc",
  "limit": 10
}
 
// Example 5: Search for specific tasks within a lead
{
  "lead_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "search": "follow up",
  "type": "follow_up"
}
 
// Example 6: Get tasks by user (alternative usage)
{
  "user_id": "12345678-1234-1234-1234-123456789012",
  "status": "active",
  "sort_by": "due_date",
  "sort_order": "asc"
}
 
// Example 7: Complex filtering with date ranges
{
  "lead_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "due_date_from": "2024-01-01T00:00:00Z",
  "due_date_to": "2024-01-31T23:59:59Z",
  "priority": "high",
  "status": "active"
}

Response Examples


// Example response with multiple tasks
{
  "success": true,
  "data": {
    "tasks": [
      {
        "id": "task_123",
        "serial_id": "TSK-2023-001234",
        "title": "Follow up with John Doe",
        "description": "Call to discuss product demo feedback",
        "address": "1234 Business Ave, Suite 100, New York, NY 10001",
        "type": "follow_up",
        "status": "active",
        "stage": "pending",
        "priority": "high",
        "user_id": "user_123",
        "site_id": "site_456",
        "lead_id": "lead_789",
        "due_date": "2023-12-15T14:00:00Z",
        "scheduled_date": "2023-12-15T14:00:00Z",
        "created_at": "2023-12-10T10:30:00Z",
        "updated_at": "2023-12-10T10:30:00Z",
        "completion_date": "2023-12-15T14:00:00Z",
        "assigned_user": {
          "id": "user_123",
          "name": "Jane Smith",
          "email": "jane.smith@example.com"
        },
        "related_lead": {
          "id": "lead_789",
          "name": "John Doe",
          "email": "john.doe@company.com",
          "company": "Acme Corp"
        },
        "site": {
          "id": "site_456",
          "name": "Main Website",
          "url": "https://example.com"
        },
        "task_categories": [
          {
            "id": "category_123",
            "name": "Marketing Campaign",
            "description": "Tasks related to marketing campaigns",
            "created_at": "2023-12-05T09:00:00Z"
          },
          {
            "id": "category_456",
            "name": "Lead Follow-up",
            "description": "Tasks for following up with leads and prospects",
            "created_at": "2023-12-01T10:15:00Z"
          }
        ],
        "task_comments": [
          {
            "id": "comment_123",
            "content": "Successfully contacted John via phone. He expressed interest in our enterprise package and wants to schedule a demo for next week.",
            "user_id": "user_123",
            "created_at": "2023-12-12T15:30:00Z",
            "updated_at": "2023-12-12T15:30:00Z",
            "user": {
              "id": "user_123",
              "name": "Jane Smith",
              "email": "jane.smith@example.com"
            }
          },
          {
            "id": "comment_124",
            "content": "Demo scheduled for December 18th at 2 PM. Sending calendar invite and preparation materials.",
            "user_id": "user_456",
            "created_at": "2023-12-12T16:45:00Z",
            "updated_at": "2023-12-12T16:45:00Z",
            "user": {
              "id": "user_456",
              "name": "Michael Johnson",
              "email": "michael.johnson@example.com"
            }
          }
        ]
      }
    ],
    "pagination": {
      "total": 42,
      "count": 1,
      "offset": 0,
      "limit": 50,
      "has_more": false
    },
    "filters_applied": {
      "user_id": "user_123",
      "status": "active"
    },
    "summary": {
      "total_tasks": 42,
      "by_status": {
        "active": 35,
        "inactive": 5,
        "archived": 2
      },
      "by_stage": {
        "pending": 20,
        "in_progress": 12,
        "review": 3,
        "completed": 7
      },
      "by_priority": {
        "low": 8,
        "medium": 22,
        "high": 10,
        "urgent": 2
      },
      "by_type": {
        "follow_up": 15,
        "marketing_campaign": 8,
        "content_creation": 12,
        "sales_demo": 5,
        "administrative": 2
      },
      "overdue_tasks": 3,
      "due_today": 5,
      "due_this_week": 18
    }
  }
}

Error Responses

All error responses follow a consistent format with appropriate HTTP status codes and descriptive error messages to help with debugging and integration.

API Tester

Prueba la API de Get Tasks directamente desde esta documentación:

Consultar Tareas

Usa este formulario para probar la consulta de tareas con filtros avanzados.