Insights

The Insights API allows you to query reporting metrics for your ClearFeed account, similar to the "Insights" section in the ClearFeed Web UI. This endpoint provides access to metrics related to the "Request" entity.

Query Insights

POST https://api.clearfeed.app/v1/rest/insights/query

Executes a query to retrieve analytical insights based on specified measures, dimensions, time dimensions, and filters.

Request Body

The request body must be a JSON object containing a query object. All keys within the query object (measures, dimensions, filter members, time dimension members) should be in snake_case.

Name	Type	Description
query	object	Required. An object defining the metrics to retrieve. See Query Object details below.

Query Object

Name	Type	Description
measures*	array	Required. An array of strings specifying the measures to calculate. See Available Measures. Must contain at least one measure.
time_dimensions*	array	Required. An array of objects defining the time dimensions for the query. See Time Dimension Object. Must contain at least one time dimension.
dimensions	array	Optional. An array of strings specifying the dimensions to group the data by. See Available Dimensions.
filters	array	Optional. An array of objects defining filters to apply to the query. See Filter Object.

Time Dimension Object

Name	Type	Description
dimension*	string	Required. The time dimension to use. See Available Time Dimensions.
granularity	string	Optional. The granularity for the time dimension (e.g., day, week, month). See Available Granularities.
date_range	string / array	Optional. The date range for the time dimension. Can be a string (see supported values below) or an array of two strings ["YYYY-MM-DD", "YYYY-MM-DD"] for a custom range. Supported string values: Today, Yesterday, This week, This month, This quarter, This year, from 7 days ago to now, from 30 days ago to now, Last week, Last month, Last quarter, Last year

Filter Object

Name	Type	Description
member*	string	Required. The dimension or measure to filter on. See Available Filters.
operator*	string	Required. The operator to use for filtering (e.g., equals, contains). See Available Operators.
values	array	Optional. An array of strings or nulls representing the values for the filter. Required for most operators; optional for set and notSet.

---

Available Measures

Measures are quantitative values, like counts or averages.

Measure Key	Description
Requests.count	Total number of requests.
Requests.first_response_request_count	Number of requests that have received a first response.
Requests.response_times_avg	Average time between a requester’s message and the next responder reply (in minutes).
Requests.response_times_p50	50th percentile of response times (median, in minutes).
Requests.response_times_p75	75th percentile of response times (in minutes).
Requests.response_times_p90	90th percentile of response times (in minutes).
Requests.response_times_p95	95th percentile of response times (in minutes).
Requests.resolution_time	Average time from request initiation to being marked as "Solved" (in minutes).
Requests.first_response_sla_breached	Count of requests that breached the First Response Time SLA.
Requests.resolution_time_sla_breached	Count of requests that breached the Resolution Time SLA.
Requests.first_response_time_avg	Average time from request creation to the first responder's reply (in minutes).
Requests.first_response_time_p50	50th percentile of first response times (median, in minutes).
Requests.first_response_time_p75	75th percentile of first response times (in minutes).
Requests.first_response_time_p90	90th percentile of first response times (in minutes).
Requests.first_response_time_p95	95th percentile of first response times (in minutes).
Requests.resolution_time_avg	Average time from request initiation to resolution (in minutes).
Requests.resolution_time_p50	50th percentile of resolution times (median, in minutes).
Requests.resolution_time_p75	75th percentile of resolution times (in minutes).
Requests.resolution_time_p90	90th percentile of resolution times (in minutes).
Requests.resolution_time_p95	95th percentile of resolution times (in minutes).
Requests.first_response_sla_breached_percent	Percentage of requests that breached the First Response Time SLA.
Requests.resolution_time_sla_breached_percent	Percentage of requests that breached the Resolution Time SLA.
Requests.first_resolution_time_avg	Average time from request creation to its first resolution (in minutes).
Requests.first_resolution_time_p50	50th percentile of first resolution times (median, in minutes).
Requests.first_resolution_time_p75	75th percentile of first resolution times (in minutes).
Requests.first_resolution_time_p90	90th percentile of first resolution times (in minutes).
Requests.first_resolution_time_p95	95th percentile of first resolution times (in minutes).
Requests.one_touch_resolution_breached	Number of requests that breached the One Touch Resolution SLA.
Requests.one_touch_resolution_breached_percent	Percentage of requests that breached the One Touch Resolution SLA.
Requests.requests_in_solved_state	Number of requests currently in a "Solved" state.
Requests.first_resolution_requests_count	Number of requests that have been in a "Solved" state at least once.
Requests.resolution_time_sla_request_count	Number of requests for which Resolution Time SLA is applicable.
Requests.first_response_time_sla_request_count	Number of requests for which First Response Time SLA is applicable.
Requests.one_touch_resolution_sla_request_count	Number of requests for which One Touch Resolution SLA is applicable.
Requests.sage_trigger_count	Number of times the Virtual Agent (Sage) was triggered.
Requests.sage_positive_feedback_count	Number of positive feedbacks ("Yes, marked as solved") for Virtual Agent solutions.
Requests.sage_negative_feedback_count	Number of negative feedbacks ("No, create a ticket") for Virtual Agent solutions.
Requests.sage_response_count	Number of times the Virtual Agent responded (with generated answers or search results).
Requests.sage_answer_count	Number of times the Virtual Agent responded specifically with generated answers.
Requests.csat_triggered_request_count	Number of requests for which a 5-point CSAT survey was triggered.
Requests.csat_received_request_count	Number of requests for which a 5-point CSAT survey response was received.
Requests.csat_response_percent	Percentage of 5-point CSAT surveys for which a response was submitted.
Requests.csat_score_avg	Average CSAT score (1-5) from received 5-point surveys.
Requests.csat_score_p50	50th percentile of CSAT scores (median, 1-5).
Requests.csat_score_p75	75th percentile of CSAT scores (1-5).
Requests.csat_score_p90	90th percentile of CSAT scores (1-5).
Requests.csat_score_p95	95th percentile of CSAT scores (1-5).
Requests.resolution_rate_percent	Percentage of requests that have been marked as resolved out of total requests.
Requests.resolved_requests_count	Total number of requests that are in a "solved" or "closed" state.
Requests.csat_received_request_count_two_point_survey	Total number of responses received for 2-point (thumbs up/down) CSAT surveys.
Requests.csat_two_point_positive_responses_count	Number of positive (thumbs up) responses in 2-point CSAT surveys.
Requests.csat_two_point_negative_responses_count	Number of negative (thumbs down) responses in 2-point CSAT surveys.

---

Available Dimensions

Dimensions are attributes used to group your measures.

Dimension Key	Description
Requests.state	The current state of the request. Possible values: open, in_progress, pending, on_hold, solved, closed.
Requests.assignee_user_id	The ID of the user assigned to the request.
Requests.priority	The priority of the request (e.g., low, normal, high, urgent).
Requests.csat_score	The CSAT score (1-5) given for the request, if a 5-point survey response was received.
Requests.custom_field_###	Custom field dimension, where ### is the ID of the custom field. For example, Requests.custom_field_42. Available for single-select, multi-select, date, number and user_select custom fields.

---

Available Time Dimensions

Time dimensions are used to group data over time intervals.

Time Dimension Key	Description
Requests.created_at	Groups data by the request creation time.
Requests.csat_triggered_at	Groups data by the time a CSAT survey was triggered.

---

Available Filters

Filters are used to narrow down the data set.

Filter Key	Description
Requests.created_at	Filters requests based on their creation timestamp (typically used with date-specific operators).
Requests.state	Filters requests by their state (see Available Dimensions for possible values).
Requests.has_ticket	Filters requests based on whether they have an associated public ticket (true or false).
Requests.priority	Filters requests by their priority level.
Requests.is_csat_triggered	Filters requests based on whether a CSAT survey was triggered for them (true or false).
Requests.csat_two_point_survey_value	Filters requests based on the value of a 2-point CSAT survey response (e.g., 1 for negative, 2 for positive).
Requests.custom_field_###	Filters requests by a custom field value, where ### is the ID of the custom field.

---

Available Granularities

Used in the granularity field of a Time Dimension Object.

• day

• week

• month

• quarter

• year

---

Available Operators

Used in the operator field of a Filter Object.

• equals

• not_equals

• contains (for string types)

• not_contains (for string types)

• gt (greater than)

• gte (greater than or equals)

• lt (less than)

• lte (less than or equals)

• set (value is present/not null)

• not_set (value is not present/null)

• in_date_range (for time dimensions)

• before_date (for time dimensions)

• after_date (for time dimensions)

---

Example Request

cURL

curl --request POST \
  --url 'https://api.clearfeed.app/v1/rest/insights/query' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": {
      "measures": [
        "Requests.count",
        "Requests.first_response_time_avg"
      ],
      "time_dimensions": [
        {
          "dimension": "Requests.created_at",
          "date_range": "Last week",
          "granularity": "day"
        }
      ],
      "dimensions": [
        "Requests.priority"
      ],
      "filters": [
        {
          "member": "Requests.state",
          "operator": "equals",
          "values": ["open"]
        }
      ]
    }
  }'

Example Response (200 OK)

{
  "insights": [
    {
      "Requests.created_at.day": "2023-10-20T00:00:00.000",
      "Requests.created_at": "2023-10-20T00:00:00.000",
      "Requests.priority": "high",
      "Requests.count": 5,
      "Requests.first_response_time_avg": 120.5
    },
    {
      "Requests.created_at.day": "2023-10-20T00:00:00.000",
      "Requests.created_at": "2023-10-20T00:00:00.000",
      "Requests.priority": "normal",
      "Requests.count": 10,
      "Requests.first_response_time_avg": 240.0
    },
    {
      "Requests.created_at.day": "2023-10-21T00:00:00.000",
      "Requests.created_at": "2023-10-21T00:00:00.000",
      "Requests.priority": "high",
      "Requests.count": 2,
      "Requests.first_response_time_avg": 90.0
    }
    // ... more data points
  ]
}

The keys in the response objects will correspond to the measures, dimensions, and time dimensions requested. Time dimensions will be suffixed with their granularity (e.g., Requests.created_at.day).

Error Responses

• 400 Bad Request: If the query is malformed (e.g., invalid measure/dimension name, incorrect filter structure, missing required fields).

• 403 Forbidden: If the API token is missing, invalid or does not have permission to access insights.

• 406 Not Acceptable: If your email is not linked to any user profile in ClearFeed.