Skip to main content

Performance Metrics API Documentation

Endpoint​

GET /api/v1/performance-metrics

Description​

This endpoint retrieves performance metrics for a specified client and period. It returns the mean time to resolve (MTTR) and mean time to respond (MTTR) for incidents within the given period, both in seconds.

URL​

https://[Base URL]/api/v1/performance-metrics

Authentication​

This API requires an API key for authentication. Include the API key in the request headers.

Headers:

  • Content-Type: application/json
  • x-api-key: [Provided by Penfield]

Query Parameters​

  • clientID (string, optional): The ID of the client. Either clientID or clientName must be provided.
  • clientName (string, optional): The name of the client. Either clientID or clientName must be provided.
  • period (string, required): The period over which to calculate the metrics. Valid values are daily, weekly, monthly, quarterly.
  • today (string, optional): The current date and time in ISO 8601 format. If not provided, the server will use the current date and time.

Example Request​

curl -G "https://[Base URL]/api/v1/performance-metrics" \
    --data-urlencode "clientID=ORG10" \
    --data-urlencode "period=weekly" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY"

Example Response​

Successful Response​

HTTP Status Code: 200 OK

Response Body:

{
  "mttResolve": 145.49,
  "mttRespond": 671.86,
  "status": "success",
  "message": "Data retrieved successfully"
}

No Data Response​

HTTP Status Code: 200 OK

Response Body:

{
  "mttResolve": null,
  "mttRespond": null,
  "status": "no_data",
  "message": "No incident data found for the specified period"
}

Invalid Period​

HTTP Status Code: 400 Bad Request

Response Body:

{
  "error": "Invalid period"
}

Missing Parameters​

HTTP Status Code: 400 Bad Request

Response Body:

{
  "error": "Both clientID and clientName are empty. Please pass either."
}

Error Handling​

  • 400 Bad Request: Returned when required query parameters are missing or invalid.
  • 404 Not Found: Returned when the client ID or client name does not exist in the system.
  • 500 Internal Server Error: Returned when an unexpected error occurs on the server.

Example Scenarios​

Scenario 1: Weekly Metrics for Client ID ORG10​

Request:

curl -G "https://[Base URL]/api/v1/performance-metrics" \
    --data-urlencode "clientID=ORG10" \
    --data-urlencode "period=weekly" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY"

Response:

{
  "mttResolve": 145.49,
  "mttRespond": 671.86,
  "status": "success",
  "message": "Data retrieved successfully"
}

Scenario 2: Daily Metrics with No Data​

Request:

curl -G "https://[Base URL]/api/v1/performance-metrics" \
    --data-urlencode "clientID=ORG10" \
    --data-urlencode "period=daily" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY"

Response:

{
  "mttResolve": null,
  "mttRespond": null,
  "status": "no_data",
  "message": "No incident data found for the specified period"
}

Scenario 3: Missing Period Parameter​

Request:

curl -G "https://[Base URL]/api/v1/performance-metrics" \
    --data-urlencode "clientID=ORG10" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY"

Response:

{
  "error": "Period is empty, please pass this value."
}

Notes​

  • The clientID or clientName must be provided to identify the client.
  • The period parameter must be one of the following values: daily, weekly, monthly, quarterly.
  • If today is not provided, the server will use the current date and time to calculate the metrics.
  • Replace YOUR_API_KEY with the actual API key provided by Penfield.