Skip to main content
POST
Get responder insight

Restrictions

Usage

  • One row per responder per time bucket; responder_ids limits which responders are returned. seconds_to_close_from/seconds_to_close_to and incident_ids are ignored.
  • Incidents are counted by creation time. Rows are sorted by ts from newest to oldest, and a bucket (or dimension value) with no incidents produces no row — missing rows mean zero. split_hours: true returns up to three rows per bucket, one per hours value.
  • Members who are neither the account owner nor an admin only get data from channels they can access; other channels are silently excluded.
  • With is_my_team: true, team_ids is narrowed to the caller’s teams. If none of the sent team_ids is one of the caller’s teams, or the caller belongs to no team, the result is empty.
  • team_ids does not filter incidents here: every member of those teams is added to responder_ids, so the rows cover the union of both.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Insight dimension-aggregation request. Extends InsightFilter with aggregation controls.

start_time
integer<int64>
required

Start time, Unix seconds. Must be greater than 0.

end_time
integer<int64>
required

End time, Unix seconds. Must be greater than start_time.

team_ids
integer<int64>[]

Filter by team IDs. At most 100 entries.

Maximum array length: 100
channel_ids
integer<int64>[]

Filter by channel IDs. At most 100 entries.

Maximum array length: 100
responder_ids
integer<int64>[]

Filter by responder member IDs. Used by /insight/responder (which responders to return) and the incident list/export (incidents any of them responded to); ignored by the account/team/channel and top-K endpoints. At most 100 entries.

Maximum array length: 100
severities
enum<string>[]

Filter by severity: Critical, Warning, Info, or Ok. At most 3 entries.

Maximum array length: 3
Available options:
Critical,
Warning,
Info,
Ok
incident_ids
string[]

Filter by incident IDs (24-character hex). Used only by the incident list and export. At most 100 entries.

Maximum array length: 100
Pattern: ^[0-9a-fA-F]{24}$
query
string

Substring match on the incident title (SQL LIKE %query%).

labels
object

Label filters (exact match).

fields
object

Custom-field filters (exact match).

orderby
enum<string>

Sort field of the incident list; only created_at (incident creation time, the default). Used by /insight/incident/list and /insight/incident/export.

Available options:
created_at
asc
boolean

Sort ascending when true, descending (default) otherwise. Used by the incident list and export; /insight/alert/topk-by-label has its own asc.

is_my_team
boolean

Restrict results to the caller's teams (intersected with team_ids when both are set). When that intersection is empty, or the caller belongs to no team, the result is empty.

time_zone
string

IANA time zone (for example Asia/Shanghai or UTC) used to cut aggregate_unit buckets; abbreviations such as EST and Etc/GMT±N are rejected. Defaults to UTC. /insight/incident/export uses it to render times, falling back to the account time zone and then Asia/Shanghai.

seconds_to_close_from
integer<int64>

Lower bound (inclusive) on time-to-close, in seconds.

Required range: x >= 0
seconds_to_close_to
integer<int64>

Upper bound (exclusive) on time-to-close, in seconds. Must be greater than seconds_to_close_from when both are set: the incident list and export reject such a range with InvalidParameter, and other endpoints return an empty result.

Required range: x >= 0
seconds_to_ack_from
integer<int64>

Lower bound (inclusive) on time-to-acknowledge, in seconds.

Required range: x >= 0
seconds_to_ack_to
integer<int64>

Upper bound (exclusive) on time-to-acknowledge, in seconds. Must be greater than seconds_to_ack_from when both are set: the incident list and export reject such a range with InvalidParameter, and other endpoints return an empty result.

Required range: x >= 0
export_fields
string[]

CSV column keys to include in the export, in the given order; unknown or duplicate keys are rejected. The valid key set differs per export endpoint — see each export operation's description. Only used by the export endpoints; at most 50 entries.

Maximum array length: 50
description_html_to_text
boolean

Strip HTML markup from the description column when exporting.

include_ever_muted
boolean

Include incidents that have ever been muted. By default, they are excluded.

split_hours
boolean

When true, each bucket is further split into work, sleep and off hours, returned as separate rows with hours set.

aggregate_unit
enum<string>

Split the range into time buckets; omit for a single bucket covering the whole range. Requires a range of at least 24 hours, and day allows at most 31 days.

  • day: calendar days in time_zone (the first bucket runs from start_time to the next midnight).
  • week: consecutive 7-day buckets starting at start_time (not aligned to Monday).
  • month: calendar months in time_zone (the first bucket runs from start_time to the 1st of the next month).
Available options:
day,
week,
month

Response

Success

Success response envelope. On every 2xx response, request_id identifies the call (also mirrored in the Flashcat-Request-Id header) and data holds the endpoint-specific payload. Failure responses use a different shape — see ErrorResponse.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

Operation-specific payload, documented in each operation's 200 response. Operations without a payload return {} or omit data entirely.