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

# Get tickets analytics by custom fields

> MCP tool to get aggregated ticket analytics data grouped by custom fields for a specific date range and team.

import Admonition from '@theme/Admonition';

### MCP tool: `get_tickets_analytics_by_custom_fields`

Get aggregated ticket analytics data grouped by custom fields for a specific date range and team.

<Admonition type="note">
  This tool provides aggregated analytics data based on custom field values, not individual ticket details. Use the search\_tickets tool for finding specific tickets.
</Admonition>

### Example prompt

```prompt theme={null}
Get ticket analytics by custom fields for the last quarter
```

<Admonition type="info">
  When you use this prompt in a chat with the model (with the MCP tool registered), the model will automatically call the <code>get\_tickets\_analytics\_by\_custom\_fields</code> tool with the correct arguments.
</Admonition>

### Parameters

<table>
  <thead>
    <tr>
      <th>Parameter</th>
      <th>Type</th>
      <th>Required</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>dateRange</td><td>object</td><td>Yes</td><td>Inclusive date range to aggregate over</td></tr>
    <tr><td>dateRange.startDate</td><td>string</td><td>Yes</td><td>Start date in YYYY-MM-DD format</td></tr>
    <tr><td>dateRange.endDate</td><td>string</td><td>Yes</td><td>End date in YYYY-MM-DD format</td></tr>
    <tr><td>teamIds</td><td>string</td><td>No</td><td>Team ID to filter by (optional)</td></tr>
    <tr><td>customFieldUids</td><td>string</td><td>Yes</td><td>Custom field UID(s) to aggregate by. Can be a single UID or comma-separated list of UIDs (e.g., "uid1" or "uid1,uid2,uid3")</td></tr>
    <tr><td>includeArchivedTickets</td><td>boolean</td><td>No</td><td>Include archived tickets (default: false)</td></tr>
    <tr><td>includeTicketMetadata</td><td>boolean</td><td>No</td><td>Include minimal ticket metadata for drill-down (default: false)</td></tr>
    <tr><td>metadataPage</td><td>number</td><td>No</td><td>Page number for metadata pagination (1-based, only used when includeTicketMetadata is true)</td></tr>
    <tr><td>metadataLimit</td><td>number</td><td>No</td><td>Limit for metadata results per page (max 500, only used when includeTicketMetadata is true)</td></tr>
  </tbody>
</table>

### Response fields

The response will contain aggregated analytics data with the following structure:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>aggregationType</td><td>string</td><td>Type of aggregation performed ("custom\_fields")</td></tr>
    <tr><td>totalTickets</td><td>number</td><td>Total number of tickets in the date range</td></tr>
    <tr><td>totalFound</td><td>number</td><td>Total number of tickets found matching criteria</td></tr>
    <tr><td>dateRange</td><td>object</td><td>The date range used for the analysis</td></tr>
    <tr><td>includeArchivedTickets</td><td>boolean</td><td>Whether archived tickets were included</td></tr>
    <tr><td>includeTicketMetadata</td><td>boolean</td><td>Whether ticket metadata was included</td></tr>
    <tr><td>aggregatedData</td><td>array</td><td>Array of team-based analytics objects with custom field breakdowns</td></tr>
  </tbody>
</table>

#### Team analytics object fields

Each team in the `aggregatedData` array contains:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>teamId</td><td>string</td><td>Team unique identifier</td></tr>
    <tr><td>teamName</td><td>string</td><td>Team name</td></tr>
    <tr><td>totalTicketsWithCustomFields</td><td>number</td><td>Total number of tickets with custom fields</td></tr>
    <tr><td>customFieldsBreakdown</td><td>array</td><td>Array of custom field breakdown objects</td></tr>
  </tbody>
</table>

#### Custom field breakdown fields

Each custom field in the `customFieldsBreakdown` array contains:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>customFieldUid</td><td>string</td><td>Custom field unique identifier</td></tr>
    <tr><td>customFieldName</td><td>string</td><td>Custom field name</td></tr>
    <tr><td>fieldType</td><td>string</td><td>Type of custom field (e.g., "date", "text", "number")</td></tr>
    <tr><td>totalTicketsWithField</td><td>number</td><td>Total number of tickets with this custom field</td></tr>
    <tr><td>values</td><td>array</td><td>Array of custom field value objects</td></tr>
  </tbody>
</table>

#### Custom field value object fields

Each value in the `values` array contains:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>value</td><td>array</td><td>Array containing the actual field value</td></tr>
    <tr><td>ticketCount</td><td>number</td><td>Number of tickets with this value</td></tr>
    <tr><td>percentage</td><td>number</td><td>Percentage of total tickets</td></tr>
    <tr><td>statusBreakdown</td><td>object</td><td>Breakdown by ticket status with counts and percentages</td></tr>
    <tr><td>metadata</td><td>object</td><td>Optional ticket metadata with pagination info and ticket details</td></tr>
  </tbody>
</table>

### Sample response

```json theme={null}
{
  "aggregationType": "custom_fields",
  "totalTickets": 61,
  "totalFound": 61,
  "dateRange": {
    "startDate": "2025-01-01",
    "endDate": "2025-09-16"
  },
  "includeArchivedTickets": false,
  "includeTicketMetadata": true,
  "aggregatedData": [
    {
      "teamId": "TRRCG55TRK",
      "teamName": "Engineering",
      "totalTicketsWithCustomFields": 61,
      "customFieldsBreakdown": [
        {
          "customFieldUid": "CF33CGNNDCX",
          "customFieldName": "Due Date",
          "fieldType": "date",
          "totalTicketsWithField": 61,
          "values": [
            {
              "value": [
                {
                  "value": "2025-09-04T18:30:00.000Z"
                }
              ],
              "ticketCount": 1,
              "percentage": 1.6,
              "statusBreakdown": {
                "Resolved": {
                  "ticketCount": 1,
                  "percentage": 100,
                  "statusId": "VYSFR7XJ10BFV3ZVVAG2HG4G35ENE"
                }
              },
              "metadata": {
                "total": 1,
                "page": 1,
                "limit": 50,
                "totalPages": 1,
                "tickets": [
                  {
                    "uid": "VST3DC4K10KHFTM58AMPG051EFY86",
                    "title": "Multiple channels in account metadata",
                    "description": "",
                    "createdAt": "2025-09-05T07:40:34.489337+00:00",
                    "updatedAt": "2025-09-12T08:19:02.649333+00:00",
                    "teamId": "TRRCG55TRK",
                    "teamName": "Engineering",
                    "statusId": "VYSFR7XJ10BFV3ZVVAG2HG4G35ENE",
                    "statusName": "Resolved",
                    "assigneeId": "UTTFIEEMOB",
                    "assigneeName": "John Doe",
                    "priorityId": "EZ8VSHRJ10Y0204YMQSVVC540JH6Q",
                    "priorityName": "Urgent",
                    "sentimentId": "GZ8VSHRJ105D86K405FZXZS40843Z",
                    "sentimentName": "Neutral"
                  }
                ]
              }
            },
            {
              "value": [
                {
                  "value": "2025-09-07T18:30:00.000Z"
                }
              ],
              "ticketCount": 11,
              "percentage": 18,
              "statusBreakdown": {
                "Resolved": {
                  "ticketCount": 10,
                  "percentage": 90.9,
                  "statusId": "VYSFR7XJ10BFV3ZVVAG2HG4G35ENE"
                },
                "Verify with customer": {
                  "ticketCount": 1,
                  "percentage": 9.1,
                  "statusId": "7KCER7XJ10QW0NAM3X86PW458AQ02"
                }
              },
              "metadata": {
                "total": 11,
                "page": 1,
                "limit": 50,
                "totalPages": 1,
                "tickets": [
                  {
                    "uid": "9JXC474K10QJQ46KTZYAKDBZV3SPQ",
                    "title": "Add isPrivate to true for all orgs except thena in apps platform",
                    "description": "",
                    "createdAt": "2025-09-03T06:32:02.887569+00:00",
                    "updatedAt": "2025-09-09T09:59:57.089136+00:00",
                    "teamId": "TRRCG55TRK",
                    "teamName": "Engineering",
                    "statusId": "VYSFR7XJ10BFV3ZVVAG2HG4G35ENE",
                    "statusName": "Resolved",
                    "assigneeId": "U11QF339UH",
                    "assigneeName": "Jane Smith",
                    "priorityId": "DZ8VSHRJ102QW2P9AKXW0025F3YAH",
                    "priorityName": "Medium",
                    "sentimentId": "GZ8VSHRJ105D86K405FZXZS40843Z",
                    "sentimentName": "Neutral"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}
```

<Admonition type="tip">
  Always pass an object as input, even if empty, to avoid errors when calling the tool directly.
</Admonition>

<Admonition type="info">
  This tool is optimized for custom field analysis and data distribution pattern understanding. Multiple custom field UIDs can be provided as a comma-separated list.
</Admonition>

<Admonition type="warning">
  The date range must be valid and startDate must be less than or equal to endDate. Use ISO 8601 date format (YYYY-MM-DD). Custom field UIDs must be valid and exist in the system.
</Admonition>

***