# 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](#query-object) details below. |
#### Query Object
| Name | Type | Description |
| --------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `measures`\* | array | Required. An array of strings specifying the measures to calculate. See [Available Measures](#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](#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](#available-dimensions). |
| `filters` | array | Optional. An array of objects defining filters to apply to the query. See [Filter Object](#filter-object). |
#### Time Dimension Object
| Name | Type | Description |
| --------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dimension`\* | string | Required. The time dimension to use. See [Available Time Dimensions](#available-time-dimensions). |
| `granularity` | string | Optional. The granularity for the time dimension (e.g., `day`, `week`, `month`). See [Available Granularities](#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](#available-filters). |
| `operator`\* | string | Required. The operator to use for filtering (e.g., `equals`, `contains`). See [Available Operators](#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.customer_id` | The ID of the customer associated with 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. |
| `Requests.collection_id` | The ID of the collection where the request was created. This corresponds to the `id` from the [Collection Object](/api/reference/api-reference/collections.md#collection-object). |
| `Requests.slack_channel_name` | The name of the Slack Channel where the request was created. |
***
### 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](#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](#time-dimension-object).
* `day`
* `week`
* `month`
* `quarter`
* `year`
***
### Available Operators
Used in the `operator` field of a [Filter Object](#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
{% tabs %}
{% tab title="cURL" %}
```bash
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"]
}
]
}
}'
```
{% endtab %}
{% endtabs %}
### Example Response (200 OK)
```json
{
"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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.clearfeed.ai/api/reference/api-reference/insights.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.