Show Meta

Retrieve Insights meta data for the authenticated site.

GET https://yoursite.desk.com/api/v2/insights3/meta

Applicable Roles

Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Administrator, Billing Administrator

Rate Limits

In addition to the general API rate limits described here, the /v2/insights3/ endpoints have an additional rate limit: due to the long-running nature of these requests and the amount of data that they return, only a single /V2/insights3/ outstanding request is allowed at a time. Any request made while another /v2/insights3/ request is outstanding will receive this body:

1
2
3
{
  "message": "Too Many Requests"
}

The general V2 response headers described here are not modifed by or used to determine the Insights3 concurrency limit.

Fields

field name description
channels enumeration for the channel field values and corresponding name
macros list of macros by ID with name and deleted boolean value
labels list of labels by ID with name and deleted boolean value
articles list of articles by ID
agents list of agents by ID
groups list of groups by ID
custom_fields list of custom fields and their values by ID
customer_custom_fields list of customer custom fields and their values by ID
case_rating_type name of the CSAT rating type. options are yes_no and four_star

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/insights3/meta \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
  "channels": {
    "20": {
      "name": "Chat"
    },
    "30": {
      "name": "Twitter"
    },
    "40": {
      "name": "Email"
    },
    "50": {
      "name": "Q&A"
    },
    "60": {
      "name": "Phone"
    },
    "70": {
      "name": "Facebook"
    }
  },
  "macros": {
    "1000": {
      "name": "Outage",
      "deleted": false
    },
    "2000": {
      "name": "Login Issues",
      "deleted": false
    }
  },
  "labels": {
    "1000": {
      "name": "Escalated",
      "deleted": false
    }
  },
  "agents": {
    "1000": {
      "name": "Gary Benitt",
      "deleted": false
    },
    "2000": {
      "name": "Alex Bard",
      "deleted": false
    }
  },
  "groups": {
    "1000": {
      "name": "Sales",
      "deleted": false
    },
    "2000": {
      "name": "Product",
      "deleted": false
    }
  },
  "custom_fields": {
    "2": {
      "id": 90283,
      "name": "Start Date"
    },
    "1:575e0dc3e4b24d90d2a216d4dc5d0f09": {
      "name": "Support Tier: Platinum"
    },
    "1:eb6d8ae6f20283755b339c0dc273988b": {
      "name": "Support Tier: Gold"
    }
  },
  "customer_custom_fields": {
    "1:cb77f5b2df38c56f826eaf1c06b060c7": {
      "name": "Tier: Not Set"
    },
    "1:f96e345fdc19cbd4cf15256c251a39a0": {
      "name": "Tier: Silver"
    }
  },
  "case_rating_type": {
    "name": "yes_no"
  }
}

Create Report

Create a report. Note that reports are not persisted so you will receive a nil href for the self link in the returned report.

POST https://yoursite.desk.com/api/v2/insights3/reports

  • It is suggested to familiarize yourself with the Business Insights UI before using the Insights API as it will aid you in visualizing the data, forming correct API requests and understanding responses.

Applicable Roles

Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Administrator, Billing Administrator

Valid Data Fields

agent_replies_per_resolve, agent_time_online, avg_handle_time, avg_interactions, avg_time_to_resolution, case_creates, case_deletes, case_reopen_rate, case_reopens, case_resolves, case_views, cases_resolved_with_macro, macro_applied, first_contact_resolution_rate, inbound_cases, inbound_interactions, label_applied, outbound_cases, outbound_interactions, resolved_cases, resolved_without_response, time_to_first_response

Valid Dimensions

action_agent, action_group, assigned_agent, assigned_group, channel, label, macro, custom_field

Valid Window Sizes

none, hour, day, week, month

Required Fields

field name description
fields One or more data fields, eg. ["agent_replies_per_resolve", "agent_time_online"]
time.min Report start time, including offset, eg. "2013-01-01T00:00:00-08:00"
time.max Report finish time, including offset, eg. "2013-03-01T00:00:00-08:00"
time.window_size One window size, eg. "day"

Optional Fields

field name description
dimension1 One dimension, eg. "channel"
dimension1_values One or more values for the dimension requested (see meta call for valid values, can be null)
dimension2 One dimension, eg. "label"
dimension2_values One or more values for the dimension requested (see meta call for valid values)
filters Conditions that further filter/refine the dataset based on labels or custom fields

Filters

Filters are structured as follows: Include/Exclude, filter object, Is/Contains (optional), string of 'Contains' search (optional), boolean to enforce case sensitive searchs (optional), array of filter object IDs

Available Filter Objects are below. Filter object IDs can be retrieved from the insights/meta endpoint.

Filter Objects

Channels, Groups, Agents, Labels, Custom Fields, Priorities, Macros, Companies, CSat Score

Filter Example

Note that this is not an entire request, just the Filter portion.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "filters": [
    [
      [
        "Include",
        "Custom Fields",
        "Is",
        "",
        false,
        [
          {
            "id": "1:909cea0c97058cfe2e3ea8d675cb08e1"
          }
        ]
      ]
    ]
  ]
}

Example Curl Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$ curl 'https://yoursite.desk.com/api/v2/insights3/reports' \
    -u email:password \
    -H 'Accept: application/json, text/plain, */*' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -X POST \
    -d '{"fields":["agent_time_online","resolved_cases"],
         "dimension1":"action_agent",
         "time":{"min":"2013-11-09T23:43:04.701Z",
                 "max":"2013-12-09T23:43:04.701Z",
                 "window_size":"none"}}'

Example Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "fields": [
    "agent_time_online",
    "resolved_cases"
  ],
  "dimension1": "action_agent",
  "time": {
    "min": "2013-11-09T23:43:04.701Z",
    "max": "2013-12-09T23:43:04.701Z",
    "window_size": "none"
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "request": {
    "fields": [
      "agent_time_online",
      "resolved_cases"
    ],
    "dimension1": "action_agent",
    "dimension1_values": null,
    "dimension2": null,
    "dimension2_values": null,
    "filters": null,
    "time": {
      "min": "2013-10-09T00:00:00-07:00",
      "max": "2013-11-09T23:59:59-08:00",
      "window_size": "none"
    }
  },
  "header": [
    "window_time",
    "dimension1_value",
    "dimension2_value",
    "agent_time_online",
    "resolved_cases"
  ],
  "data": [
    [
      null,
      1000,
      null,
      null,
      21
    ],
    [
      null,
      2000,
      null,
      null,
      20
    ],
    [
      null,
      3000,
      null,
      null,
      1
    ]
  ]
}

Example Request Body With Filters

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
  "fields": [
    "agent_time_online",
    "resolved_cases"
  ],
  "dimension1": "action_agent",
  "time": {
    "min": "2013-11-09T23:43:04.701Z",
    "max": "2013-12-09T23:43:04.701Z",
    "window_size": "none"
  },
  "filters": [
    [
      [
        "Include",
        "Labels",
        [
          {
            "id": "1"
          },
          {
            "id": "2"
          }
        ]
      ],
      [
        "Include",
        "Custom Fields",
        [
          {
            "id": "1:29e7454f4ca14e12d30bc085ff0e1eed"
          }
        ]
      ]
    ],
    [
      [
        "Exclude",
        "Labels",
        [
          {
            "id": "5"
          }
        ]
      ],
      [
        "Include",
        "Labels",
        [
          {
            "id": "6"
          }
        ]
      ]
    ]
  ]
}

Example Request Body For Macro Applied

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "fields": [
    "macro_applied"
  ],
  "dimension1": "macro",
  "dimension2": "channel",
  "dimension2_values": [
    20,
    30,
    40,
    50,
    60,
    70
  ],
  "time": {
    "min": "2016-03-10T21:06:41.772Z",
    "max": "2017-03-17T21:06:41.772Z",
    "window_size": "none"
  }
}