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

> MCP tool to get aggregated ticket analytics data grouped by time periods (daily, weekly, monthly, quarterly) for a specific date range.

import Admonition from '@theme/Admonition';

### MCP tool: `get_tickets_analytics_by_time`

Get aggregated ticket analytics data grouped by time periods (daily, weekly, monthly, quarterly) for a specific date range.

<Admonition type="note">
  This tool provides time-series analytics data, not individual ticket details. Use the search\_tickets tool for finding specific tickets.
</Admonition>

### Example prompt

```prompt theme={null}
Get ticket analytics by time for the last quarter with monthly granularity
```

<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\_time</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>timeGranularity</td><td>string</td><td>Yes</td><td>Time granularity: daily, weekly, monthly, or quarterly</td></tr>
    <tr><td>teamIds</td><td>array</td><td>No</td><td>Optional array of team IDs to filter by</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 200, only used when includeTicketMetadata is true)</td></tr>
  </tbody>
</table>

### Time granularity options

* `daily` - Group data by day
* `weekly` - Group data by week
* `monthly` - Group data by month
* `quarterly` - Group data by quarter

### 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 ("time")</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>summary</td><td>object</td><td>Summary statistics across all time periods</td></tr>
    <tr><td>aggregatedData</td><td>array</td><td>Array of team-based analytics objects with time breakdowns</td></tr>
  </tbody>
</table>

#### Summary object fields

The `summary` object contains:

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

  <tbody>
    <tr><td>avgTicketsPerPeriod</td><td>number</td><td>Average number of tickets per time period</td></tr>
    <tr><td>peakPeriod</td><td>string</td><td>Time period with the highest ticket count</td></tr>
    <tr><td>peakTicketCount</td><td>number</td><td>Number of tickets in the peak period</td></tr>
    <tr><td>lowestPeriod</td><td>string</td><td>Time period with the lowest ticket count</td></tr>
    <tr><td>lowestTicketCount</td><td>number</td><td>Number of tickets in the lowest period</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>total</td><td>number</td><td>Total number of tickets for this team</td></tr>
    <tr><td>percentage</td><td>number</td><td>Percentage of total tickets</td></tr>
    <tr><td>timeBreakdown</td><td>object</td><td>Breakdown by time periods with detailed metrics</td></tr>
  </tbody>
</table>

#### Time period breakdown fields

Each time period in the `timeBreakdown` object contains:

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

  <tbody>
    <tr><td>period</td><td>string</td><td>The time period identifier (e.g., "2025-08-13")</td></tr>
    <tr><td>periodStart</td><td>string</td><td>Start timestamp of the time period</td></tr>
    <tr><td>periodEnd</td><td>string</td><td>End timestamp of the time period</td></tr>
    <tr><td>ticketCount</td><td>number</td><td>Number of tickets in this time period</td></tr>
    <tr><td>createdCount</td><td>number</td><td>Number of tickets created in this time period</td></tr>
    <tr><td>statusBreakdown</td><td>object</td><td>Breakdown by ticket status with counts and percentages</td></tr>
    <tr><td>priorityBreakdown</td><td>object</td><td>Breakdown by ticket priority with counts and percentages</td></tr>
    <tr><td>assigneeBreakdown</td><td>object</td><td>Breakdown by assignee with counts and percentages</td></tr>
    <tr><td>sourceBreakdown</td><td>object</td><td>Breakdown by ticket source</td></tr>
  </tbody>
</table>

### Sample response

```json theme={null}
{
  "aggregationType": "time",
  "totalTickets": 2,
  "totalFound": 2,
  "dateRange": {
    "startDate": "2025-01-01",
    "endDate": "2025-09-16"
  },
  "includeArchivedTickets": false,
  "includeTicketMetadata": false,
  "summary": {
    "avgTicketsPerPeriod": 1,
    "peakPeriod": "2025-08-13",
    "peakTicketCount": 1,
    "lowestPeriod": "2025-08-13",
    "lowestTicketCount": 1
  },
  "aggregatedData": [
    {
      "teamId": "THEVVHPCCER33E",
      "teamName": "Engineering",
      "total": 2,
      "percentage": 100,
      "timeBreakdown": {
        "2025-08-13": {
          "period": "2025-08-13",
          "periodStart": "2025-08-13T00:00:00.000Z",
          "periodEnd": "2025-08-14T00:00:00.000Z",
          "ticketCount": 1,
          "createdCount": 1,
          "statusBreakdown": {
            "Open": {
              "count": 1,
              "percentage": 100,
              "statusId": "3SC6BH2K10X5BSCXF2MFWVYZVYNFX"
            }
          },
          "priorityBreakdown": {
            "Urgent": {
              "count": 1,
              "percentage": 100,
              "priorityId": "CSC6BH2K100SATQR0ZS6KHBW1DFPK"
            }
          },
          "assigneeBreakdown": {
            "John Doe": {
              "count": 1,
              "percentage": 100,
              "assigneeId": "UTHOOQNUUXZQQ3",
              "assigneeEmail": "john.doe@thena.ai"
            }
          },
          "sourceBreakdown": {
            "manual": 1
          }
        },
        "2025-08-20": {
          "period": "2025-08-20",
          "periodStart": "2025-08-20T00:00:00.000Z",
          "periodEnd": "2025-08-21T00:00:00.000Z",
          "ticketCount": 1,
          "createdCount": 1,
          "statusBreakdown": {
            "Open": {
              "count": 1,
              "percentage": 100,
              "statusId": "3SC6BH2K10X5BSCXF2MFWVYZVYNFX"
            }
          },
          "priorityBreakdown": {
            "Medium": {
              "count": 1,
              "percentage": 100,
              "priorityId": "CSC6BH2K10XR2ZVVY84VV8506YN80"
            }
          },
          "assigneeBreakdown": {
            "John Doe": {
              "count": 1,
              "percentage": 100,
              "assigneeId": "UTHOOQNUUXZQQ3",
              "assigneeEmail": "john.doe@thena.ai"
            }
          },
          "sourceBreakdown": {
            "manual": 1
          }
        }
      }
    }
  ]
}
```

<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 trend analysis and performance tracking over time. Choose the appropriate time granularity based on your analysis needs - daily for detailed trends, quarterly for high-level overviews.
</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). Time granularity must be one of: daily, weekly, monthly, quarterly.
</Admonition>

***