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

Links

rel class description

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
{
  "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": {
    "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"
    }
  }
}

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, 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

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

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"
          }
        ]
      ]
    ]
  ]
}