# List tags

Retrieve all tags for a project with optional filtering and sorting.

Tags are used for categorizing budget line items and enable advanced filtering
capabilities across budget data. Each tag includes financial totals aggregated
from all associated budget line items.


Endpoint: GET /projects/{projectId}/tags
Version: 1.0.0
Security: ApiKeyAuth

## Path parameters:

  - `projectId` (string, required)
    Project identifier (alias or ID)
    Example: "nike-spring-2024"

## Query parameters:

  - `name` (string)
    Filter tags by name (partial match search)
    Example: "Post-Production"

  - `sortBy` (string)
    Field to sort by
    Enum: "name"

  - `sortOrder` (string)
    Sort direction
    Enum: "asc", "desc"

  - `idMode` (string)
    ID interpretation mode. Controls how path and query parameter IDs (like lineId, accountId, phaseId) are interpreted - 'user' for human-readable IDs (account codes, phase names), 'system' for database IDs (UUIDs/nanoids). Also affects the format of IDs in responses.
    Enum: "user", "system"

## Response 200 fields (application/json):

  - `tags` (array, required)
    Array of tags with their financial totals

  - `tags.id` (string, required)
    Unique tag identifier (same as tag name)
    Example: "Post-Production"

  - `tags.name` (string, required)
    Tag name (1-100 characters, immutable after creation)
    Example: "Post-Production"

  - `tags.color` (string)
    Optional hex color code for visual identification
    Example: "#3B82F6"

  - `tags.description` (string)
    Optional description for documentation purposes
    Example: "Post-production and VFX expenses"

  - `tags.totals` (object, required)
    Financial totals aggregated from all budget line items assigned to this tag

  - `tags.totals.phaseTotals` (object, required)
    Total amounts by phase ID. Keys depend on idMode parameter:
- idMode=user: phase aliases (e.g., "estimate", "actual")
- idMode=system: internal database IDs (UUID strings)
    Example: {"estimate":15000,"actual":12500}

  - `tags.totals.fringeTotals` (object, required)
    Fringe benefit totals by phase ID. Keys follow same format as phaseTotals.
    Example: {"estimate":2250,"actual":1875}

  - `tags.totals.actualTotal` (number, required)
    Total actual expenses for this tag across all phases
    Example: 14375

## Response 401 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (object)
    Additional error details
    Example: {"field":"projectId","reason":"Project not found"}

  - `code` (string)
    Error code
    Example: "VALIDATION_ERROR"

## Response 404 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (object)
    Additional error details
    Example: {"field":"projectId","reason":"Project not found"}

  - `code` (string)
    Error code
    Example: "VALIDATION_ERROR"

## Response 500 fields (application/json):

  - `error` (string, required)
    Error message
    Example: "Invalid request parameters"

  - `details` (object)
    Additional error details
    Example: {"field":"projectId","reason":"Project not found"}

  - `code` (string)
    Error code
    Example: "VALIDATION_ERROR"