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

# Find Task

> Search for a specific task by name within a workspace with comprehensive task details, assignments, and project information.

## Overview

The Find Task endpoint allows you to search for a specific task by name within a workspace. This endpoint returns detailed task information including project details, assignee information, time tracking data, and task status for use in Zapier workflows.

<Note>
  This endpoint supports both GET and POST methods and performs a case-insensitive partial match search on the task name, returning comprehensive task metadata including assignee details and project context.
</Note>

## Authentication

All requests require a valid API key in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Find Task

### POST Method

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://app.timetracker.in/api/integrations/zapier/triggers/tasks/find' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
      "name": "Implement user authentication"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.timetracker.in/api/integrations/zapier/triggers/tasks/find', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      workspace_id: 'w1b2c3d4-e5f6-7890-abcd-ef0987654321',
      name: 'Implement user authentication'
    })
  });

  const tasks = await response.json();
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.timetracker.in/api/integrations/zapier/triggers/tasks/find"
  headers = {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY"
  }
  data = {
      "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
      "name": "Implement user authentication"
  }

  response = requests.post(url, headers=headers, json=data)
  tasks = response.json()
  ```
</CodeGroup>

### GET Method

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://app.timetracker.in/api/integrations/zapier/triggers/tasks/find?workspace_id=w1b2c3d4-e5f6-7890-abcd-ef0987654321&name=Implement%20user%20authentication' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    workspace_id: 'w1b2c3d4-e5f6-7890-abcd-ef0987654321',
    name: 'Implement user authentication'
  });

  const response = await fetch(`https://app.timetracker.in/api/integrations/zapier/triggers/tasks/find?${params}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const tasks = await response.json();
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.timetracker.in/api/integrations/zapier/triggers/tasks/find"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY"
  }
  params = {
      "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
      "name": "Implement user authentication"
  }

  response = requests.get(url, headers=headers, params=params)
  tasks = response.json()
  ```
</CodeGroup>

### Request Parameters

<ParamField path="workspace_id" type="string" required>
  The unique identifier of the workspace to search within. Must be a valid UUID format.

  **Example:** `"w1b2c3d4-e5f6-7890-abcd-ef0987654321"`
</ParamField>

<ParamField path="name" type="string" required>
  The task name to search for. Performs case-insensitive partial matching.

  **Example:** `"Implement user authentication"` or `"authentication"` (will match "Implement user authentication")
</ParamField>

## Response

### Success Response

Returns an array containing the matching task object with comprehensive details, or an empty array if no match is found:

```json theme={null}
[
  {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Implement user authentication",
    "description": "Add OAuth2 authentication to the mobile app",
    "status": "in-progress",
    "priority": "high",
    "estimated_hours": 8.0,
    "actual_hours": 4.5,
    "due_date": "2024-01-15T00:00:00.000Z",
    "project_id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "project_name": "Mobile App Development",
    "project_status": "active",
    "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "workspace_name": "Development Team",
    "client_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "client_name": "TechCorp Inc.",
    "assignees": [
      {
        "id": "tm1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "user_id": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "user_name": "John Doe",
        "user_email": "john@example.com",
        "role_name": "Developer"
      }
    ],
    "time_entries_count": 3,
    "created_at": "2024-01-10T10:00:00.000Z",
    "updated_at": "2024-01-12T15:30:00.000Z"
  }
]
```

<ResponseField name="id" type="string">
  Unique task identifier (UUID format)
</ResponseField>

<ResponseField name="name" type="string">
  Task name
</ResponseField>

<ResponseField name="description" type="string">
  Detailed task description
</ResponseField>

<ResponseField name="status" type="string">
  Current task status

  * `todo` - Task is not yet started
  * `in-progress` - Task is currently being worked on
  * `completed` - Task has been finished
</ResponseField>

<ResponseField name="priority" type="string">
  Task priority level

  * `low` - Low priority task
  * `medium` - Standard priority task
  * `high` - High priority task
</ResponseField>

<ResponseField name="estimated_hours" type="number">
  Estimated time to complete the task in hours
</ResponseField>

<ResponseField name="actual_hours" type="number">
  Actual time spent on the task in hours
</ResponseField>

<ResponseField name="due_date" type="string">
  ISO 8601 timestamp of the task due date (null if no due date set)
</ResponseField>

<ResponseField name="project_id" type="string">
  Unique identifier of the project containing this task
</ResponseField>

<ResponseField name="project_name" type="string">
  Name of the project containing this task
</ResponseField>

<ResponseField name="project_status" type="string">
  Current status of the project containing this task
</ResponseField>

<ResponseField name="workspace_id" type="string">
  Unique identifier of the workspace containing this task
</ResponseField>

<ResponseField name="workspace_name" type="string">
  Name of the workspace containing this task
</ResponseField>

<ResponseField name="client_id" type="string">
  Unique identifier of the client associated with the project (null if no client)
</ResponseField>

<ResponseField name="client_name" type="string">
  Name of the client associated with the project (null if no client)
</ResponseField>

<ResponseField name="assignees" type="array">
  Array of team members assigned to this task

  <Expandable title="Assignee Object Properties">
    <ResponseField name="id" type="string">
      Unique team member identifier
    </ResponseField>

    <ResponseField name="user_id" type="string">
      Unique user identifier
    </ResponseField>

    <ResponseField name="user_name" type="string">
      Full name of the assigned user
    </ResponseField>

    <ResponseField name="user_email" type="string">
      Email address of the assigned user
    </ResponseField>

    <ResponseField name="role_name" type="string">
      Role name of the assigned user
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="time_entries_count" type="integer">
  Number of time entries logged for this task
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when task was created
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp when task was last modified
</ResponseField>

### No Results Response

When no matching task is found, returns an empty array:

```json theme={null}
[]
```

### Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request - Invalid Parameters">
    ```json theme={null}
    {
      "error": "Invalid request parameters"
    }
    ```

    **Cause**: Missing required fields or invalid UUID format\
    **Solution**: Ensure both `workspace_id` and `name` are provided with valid formats
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={null}
    {
      "error": "Unauthorized"
    }
    ```

    **Cause**: Invalid or missing API key\
    **Solution**: Verify your API key is correct and properly formatted
  </Accordion>

  <Accordion title="500 Internal Server Error">
    ```json theme={null}
    {
      "error": "Internal server error"
    }
    ```

    **Cause**: Server-side error during search\
    **Solution**: Retry the request or contact support if the issue persists
  </Accordion>
</AccordionGroup>

## Search Behavior

### Partial Matching

The search performs case-insensitive partial matching on the task name:

* **Input**: `"auth"` → **Matches**: "Implement user authentication", "Setup auth middleware", "Test authentication flow"
* **Input**: `"implement"` → **Matches**: "Implement user authentication", "Implement payment system", "Implement API endpoints"

### Workspace Scoping

<Warning>
  **Workspace Isolation**: The search is limited to tasks within the specified workspace. Tasks from other workspaces are not accessible, even if they match the name criteria.
</Warning>

### Result Ordering

Results are ordered by creation date (newest first), so the most recently created matching task appears first.

## Task Management Features

### Status Tracking

Tasks progress through different statuses:

<AccordionGroup>
  <Accordion title="Todo">
    **Status**: `todo`\
    **Description**: Task is created but not yet started\
    **Use Case**: Planning and prioritization phase
  </Accordion>

  <Accordion title="In Progress">
    **Status**: `in-progress`\
    **Description**: Task is currently being worked on\
    **Use Case**: Active development or work phase
  </Accordion>

  <Accordion title="Completed">
    **Status**: `completed`\
    **Description**: Task has been finished\
    **Use Case**: Work completed and ready for review
  </Accordion>
</AccordionGroup>

### Priority Levels

Tasks can be assigned different priority levels:

* **High Priority** (`high`) - Urgent tasks requiring immediate attention
* **Medium Priority** (`medium`) - Standard tasks with normal priority
* **Low Priority** (`low`) - Tasks that can be completed when time permits

### Time Tracking

Tasks include comprehensive time tracking information:

* **Estimated Hours** - Planned time allocation
* **Actual Hours** - Time actually spent on the task
* **Time Entries Count** - Number of individual time entries logged

## Zapier Integration Usage

### Common Use Cases

<AccordionGroup>
  <Accordion title="Task Selection in Workflows">
    **Use Case**: Allow users to select existing tasks when logging time entries or updating task status in Zapier workflows.

    **Implementation**: Use this endpoint to populate dropdown lists or validate task selections.
  </Accordion>

  <Accordion title="Task Status Monitoring">
    **Use Case**: Monitor task progress and status changes for automated notifications or project management workflows.

    **Implementation**: Use the `status`, `priority`, and `due_date` fields to track task health and deadlines.
  </Accordion>

  <Accordion title="Time Tracking Integration">
    **Use Case**: Create time entries or generate reports based on task information and time tracking data.

    **Implementation**: Use `estimated_hours`, `actual_hours`, and `time_entries_count` for time management workflows.
  </Accordion>

  <Accordion title="Assignment Management">
    **Use Case**: Manage task assignments and notify team members about task updates or new assignments.

    **Implementation**: Use the `assignees` array to identify responsible team members and send notifications.
  </Accordion>
</AccordionGroup>

### Zapier Field Mapping

When setting up Zapier actions, you can map these task fields:

* **Task ID** → `id` (for referencing in other API calls)
* **Task Name** → `name` (for display purposes)
* **Task Status** → `status` (for conditional logic)
* **Task Priority** → `priority` (for prioritization workflows)
* **Project Information** → `project_id`, `project_name` (for project association)
* **Client Information** → `client_id`, `client_name` (for client association)
* **Assignee Information** → `assignees` array (for team member notifications)
* **Time Data** → `estimated_hours`, `actual_hours`, `time_entries_count` (for time tracking)

## Assignment Management

### Assignee Information

The `assignees` array provides detailed information about team members assigned to the task:

* **Team Member ID** - For referencing in other API calls
* **User Information** - Name and email for notifications
* **Role Information** - Role name for context and permissions

### Multi-Assignment Support

Tasks can have multiple assignees, allowing for:

* **Collaborative Work** - Multiple team members working on the same task
* **Role-Based Assignment** - Different team members with different responsibilities
* **Backup Assignment** - Primary and secondary assignees

## Best Practices

<Check>
  **Task Management**:

  * Use descriptive, specific task names for better searchability
  * Set realistic estimated hours for better project planning
  * Use priority levels consistently across your workspace
  * Keep task descriptions detailed for better context
  * Regularly update task status to maintain accurate project tracking
</Check>

<Tip>
  **Pro Tip**: Use the time tracking data (`estimated_hours` vs `actual_hours`) to improve future project estimates and identify tasks that consistently take longer than expected.
</Tip>

<Warning>
  **Due Date Management**: Always check if `due_date` is null before using it in date-based logic, as not all tasks have due dates set.
</Warning>

## Rate Limits

This endpoint follows standard API rate limiting:

* **Rate Limit**: 100 requests per minute per API key
* **Burst Limit**: 10 requests per second
* **Reset Period**: Rolling 60-second window

<Info>
  **Rate Limit Headers**: Response headers include current usage information:

  * `X-RateLimit-Limit`: Maximum requests per window
  * `X-RateLimit-Remaining`: Remaining requests in current window
  * `X-RateLimit-Reset`: Timestamp when the limit resets
</Info>