Performance Management Reports Explore API

Overview

The Performance Management (PM) Reports API lets you generate and retrieve two related report types:

• pm_result_analysis — agent-level performance results against goals and team means
• pm_improvement_and_attainment — month-over-month improvement and attainment metrics, aggregated at the queue/interval level

Both report types share the same endpoints, authentication model, rate limits, and job lifecycle. The only difference between them is the schema of the output file each produces.

Authentication

All requests are authenticated using JWT via API Gateway. Requests must include a token with the appropriate scope.

Report Lifecycle

Reports are generated asynchronously using a job-based model:

1. Create a job — submit a POST request specifying the report type, format, timezone, and timespan.
2. Poll for status — check the job's status via GET until it reaches done.
3. Download the file — once the job is done, retrieve the output file via the file endpoint.

Create a Job

POST /data/reports/{report_type}/jobs

{
  "name": "pm",
  "format": "csv",
  "timezone": "UTC",
  "timespan": {
    "from": "2026-01-01T02:00:00",
    "to": "2026-02-01T04:00:00"
  }
}

{
  "job": {
    "id": "f8f7fc12-5ed8-4976-a128-200eecbdafab",
    "name": "pm",
    "created_at": "2026-07-31T07:11:31",
    "status": "created",
    "type": "pm_improvement_and_attainment",
    "format": "csv",
    "timespan": {
      "from": "2026-01-01T02:00:00",
      "to": "2026-02-01T04:00:00"
    },
    "timezone": "UTC"
  }
}

Check Job Status

GET /data/reports/{report_type}/jobs

{
  "_embedded": {
    "jobs": [
      {
        "id": "c5e1c32c-312d-49ae-82a8-ffdb03548d33",
        "name": "pm",
        "created_at": "2026-07-17T09:11:05",
        "status": "done",
        "type": "pm_result_analysis",
        "format": "csv",
        "timespan": {
          "from": "2026-01-01T02:00:00",
          "to": "2026-02-01T04:00:00"
        },
        "timezone": "UTC",
        "_links": {
          "self": { "href": "https://api.talkdeskapp.com/data/reports/pm_result_analysis/jobs/c5e1c32c-312d-49ae-82a8-ffdb03548d33" },
          "files": { "href": "https://api.talkdeskapp.com/data/reports/pm_result_analysis/files/c5e1c32c-312d-49ae-82a8-ffdb03548d33" }
        }
      }
    ]
  }
}

Download the Report File

GET /data/reports/{report_type}/files/{job_id}

Returns the generated report file in the requested format (csv, json, or json_bulk).

Report Schemas

pm_result_analysis

Returns agent-level rows with performance results against goals and team means.

Agent,Agent ID,Agent Email,Agent Name,Measure Name,Team ID,Team Name,Queue Type,Queue Name,Volume,Result Value,Goal Value,Mean Value,Interval Type,LeaderBoard Date
AGENT-PLACEHOLDER-001,AGENT-ID-PLACEHOLDER-001,[email protected],AGENT-NAME-PLACEHOLDER-001,SCHEDULE ADHERENCE,TEAM-ID-PLACEHOLDER-001,Example Team,All,,63000,17.14,31.25,15.21,Monthly,2026-02-01

pm_improvement_and_attainment

Returns aggregated month-over-month improvement and attainment metrics.

Month Comparison - Current vs Previous Month,Measure Name,Interval Type,Queue Type,Count Agent Positive Result - Current vs Previous Month,Count Agent NON Positive Result - Current vs Previous Month,Improvement,Count Agent Positive Attainment - Improvement and Goal,Count Agent NON Positive Attainment - Improvement and Goal,leaderboard_pm_trend.attainment_1,Count Distinct Agent
January-2026 - February-2026,SCHEDULE ADHERENCE,Monthly,All,4,10,0.2857142857142857,0,14,0.0,14

Supported Formats

Reports can be generated in the following formats:

• csv
• json
• json_bulk

Rate Limits

• 25 requests/second per account across all /data/reports/** endpoints, shared between both report types.

Job Quotas

• Maximum of 15 simultaneous report jobs per account, across all report types combined.
• Exceeding this quota returns an HTTP 429 with error code family data_reports_not_enough_quota_error.

Service Level Objectives

Audit Logging

Access to report data is audited. A get_report_data event is recorded whenever a report file is fetched via the file download endpoint. Job creation and status polling are not separately audited.

Error Handling