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

> Search for a specific tag by name within a workspace for categorization and organization purposes.

## Overview

The Find Tag endpoint allows you to search for a specific tag by name within a workspace. Tags are used to categorize and organize time entries, making it easier to track different types of work or project phases.

<Note>
  This endpoint performs a case-insensitive partial match search on the tag name and returns tag details including color coding and description for use in Zapier workflows.
</Note>

## Authentication

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

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

## Find Tag

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

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

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

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

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

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

### Request Body

<ParamField body="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 body="name" type="string" required>
  The tag name to search for. Performs case-insensitive partial matching.

  **Example:** `"Development"` or `"dev"` (will match "Development")
</ParamField>

## Response

### Success Response

Returns an array containing the matching tag object, or an empty array if no match is found:

```json theme={null}
[
  {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Development",
    "color": "#FF6B6B",
    "description": "Tasks related to software development",
    "workspace_id": "w1b2c3d4-e5f6-7890-abcd-ef0987654321",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]
```

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

<ResponseField name="name" type="string">
  Tag name used for categorization
</ResponseField>

<ResponseField name="color" type="string">
  Hex color code for visual identification of the tag
</ResponseField>

<ResponseField name="description" type="string">
  Optional description explaining the tag's purpose or usage
</ResponseField>

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

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

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

### No Results Response

When no matching tag 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 tag name:

* **Input**: `"dev"` → **Matches**: "Development", "DevOps", "Frontend Dev"
* **Input**: `"bug"` → **Matches**: "Bug Fix", "Bug Report", "Bug Testing"

### Workspace Scoping

<Warning>
  **Workspace Isolation**: The search is limited to tags within the specified workspace. Tags 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 tag appears first.

## Tag Usage and Organization

### Common Tag Categories

Tags are typically used to categorize work by:

<AccordionGroup>
  <Accordion title="Work Type">
    * **Development** - Software development tasks
    * **Design** - UI/UX design work
    * **Testing** - Quality assurance activities
    * **Research** - Investigation and analysis
  </Accordion>

  <Accordion title="Project Phase">
    * **Planning** - Project planning and setup
    * **Implementation** - Active development phase
    * **Review** - Code review and testing
    * **Deployment** - Release and deployment activities
  </Accordion>

  <Accordion title="Priority Level">
    * **High Priority** - Urgent tasks
    * **Medium Priority** - Standard tasks
    * **Low Priority** - Non-urgent tasks
  </Accordion>

  <Accordion title="Client/Department">
    * **Client A** - Work for specific client
    * **Marketing** - Marketing department tasks
    * **Sales** - Sales-related activities
  </Accordion>
</AccordionGroup>

## Zapier Integration Usage

### Common Use Cases

<AccordionGroup>
  <Accordion title="Tag Selection in Workflows">
    **Use Case**: Allow users to select existing tags when creating time entries or categorizing work in Zapier workflows.

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

  <Accordion title="Time Entry Categorization">
    **Use Case**: Automatically categorize time entries based on project type or work category.

    **Implementation**: Use tag information to apply appropriate categorization to time entries.
  </Accordion>

  <Accordion title="Reporting and Analytics">
    **Use Case**: Generate reports based on tag usage and time allocation across different categories.

    **Implementation**: Use tag data to group and analyze time tracking data.
  </Accordion>

  <Accordion title="Visual Organization">
    **Use Case**: Apply color coding and visual organization to time entries and reports.

    **Implementation**: Use the `color` field to maintain consistent visual organization across systems.
  </Accordion>
</AccordionGroup>

### Zapier Field Mapping

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

* **Tag ID** → `id` (for referencing in other API calls)
* **Tag Name** → `name` (for display and categorization)
* **Tag Color** → `color` (for visual organization)
* **Tag Description** → `description` (for context and documentation)
* **Workspace ID** → `workspace_id` (for workspace association)

## Color Coding

Tags support hex color codes for visual identification:

### Common Color Schemes

* **Red** (`#FF6B6B`) - High priority or urgent tasks
* **Blue** (`#3B82F6`) - Development or technical work
* **Green** (`#10B981`) - Completed or successful tasks
* **Yellow** (`#F59E0B`) - In-progress or pending tasks
* **Purple** (`#8B5CF6`) - Design or creative work
* **Gray** (`#6B7280`) - Administrative or support tasks

### Color Usage Best Practices

<Check>
  **Visual Organization**:

  * Use consistent color schemes across your workspace
  * Consider color accessibility for team members with color vision differences
  * Use colors to quickly identify work types or priorities
  * Maintain color consistency when integrating with external systems
</Check>

## Best Practices

<Check>
  **Tag Management**:

  * Use descriptive, consistent naming conventions
  * Keep tag names concise but clear
  * Use colors to enhance visual organization
  * Regularly review and clean up unused tags
  * Document tag purposes in descriptions
</Check>

<Tip>
  **Pro Tip**: Create a tag hierarchy or naming convention (e.g., "WorkType:Development", "Priority:High") to make searching and organization more systematic.
</Tip>

<Warning>
  **Tag Limits**: While there's no hard limit on the number of tags, consider keeping the total number manageable to avoid overwhelming users in dropdown lists and interfaces.
</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>