Skip to main content

Try the live demo!

Search

Get Overview Tag Distribution

Requires the `reports:manage` permission.

GET /api/v1/reports/overview/tags

Requires the reports:manage permission.

Authentication

Use an agent API key and secret.

Parameters

All parameters are query parameters. All parameters are optional.

Name Type Description
days integer Number of past days to include. 0 means today only. Values outside 0-365 are clamped. default: 0 minimum: 0 maximum: 365

Responses

200

Report retrieved successfully

Content type: application/json.

All fields are optional.

Field Type Description
status string example: "success"
data object
data.top_tags array of object Up to 10 tags with the most conversations.
data.top_tags[].tag_id integer example: 1
data.top_tags[].tag_name string example: "billing"
data.top_tags[].count integer example: 5
data.tagged_conversations integer example: 30
data.untagged_conversations integer example: 10
data.tagged_percentage number example: 75

401

Unauthorized

Content type: application/json.

All fields are optional.

Field Type Description
status string example: "error"
message string Error message example: "Invalid request"
data unspecified Additional error data nullable: true
error_type string (enum) enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"]

403

Permission denied

Content type: application/json.

Response fields match the 401 response.

500

Internal server error

Content type: application/json.

Response fields match the 401 response.

Specification

Download the complete OpenAPI specification.

OpenAPI definition for this endpoint
openapi: 3.0.0
info:
  title: libredesk API
  description: >-
    REST API documentation for libredesk helpdesk system.


    ## Authentication


    The libredesk API supports two authentication methods:


    ### 1. Basic Authentication

    Use your API key and secret with Basic authentication:

    ```

    Authorization: Basic <base64_encoded_api_key:api_secret>

    ```


    ### 2. Token Authentication  

    Use your API key and secret with token authentication:

    ```

    Authorization: token api_key:api_secret

    ```


    To obtain API credentials, generate them from your agent profile in the
    libredesk dashboard.
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Local development server
security:
  - basicAuth: []
  - tokenAuth: []
paths:
  /api/v1/reports/overview/tags:
    get:
      tags:
        - Reports
      summary: Get Overview Tag Distribution
      description: Requires the `reports:manage` permission.
      operationId: handleOverviewTagDistribution
      parameters:
        - name: days
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 365
            default: 0
          description: >-
            Number of past days to include. 0 means today only. Values outside
            0-365 are clamped.
      responses:
        '200':
          description: Report retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportOverviewTagDistributionResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - basicAuth: []
        - tokenAuth: []
components:
  schemas:
    ReportOverviewTagDistributionResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/ReportOverviewTagDistribution'
    ErrorResponse:
      type: object
      description: Error response format
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Error message
          example: Invalid request
        data:
          nullable: true
          description: Additional error data
        error_type:
          type: string
          enum:
            - GeneralException
            - PermissionException
            - InputException
            - DataException
            - NetworkException
            - NotFoundException
            - ConflictException
            - UnauthorizedException
            - RateLimitException
    ReportOverviewTagDistribution:
      type: object
      properties:
        top_tags:
          type: array
          items:
            $ref: '#/components/schemas/ReportTagCount'
          description: Up to 10 tags with the most conversations.
        tagged_conversations:
          type: integer
          example: 30
        untagged_conversations:
          type: integer
          example: 10
        tagged_percentage:
          type: number
          example: 75
    ReportTagCount:
      type: object
      properties:
        tag_id:
          type: integer
          example: 1
        tag_name:
          type: string
          example: billing
        count:
          type: integer
          example: 5
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication using base64 encoded API key and secret. Format:
        `Authorization: Basic <base64(api_key:api_secret)>`
    tokenAuth:
      type: apiKey
      name: Authorization
      in: header
      description: >-
        Token authentication using API key and secret. Format: `Authorization:
        token api_key:api_secret`

Was this article helpful?