Docs / API Reference / Query Reporting
API v1.3.6

Query Reporting

Every API request is logged server-side and assigned a unique log ID returned in a response header. When something goes wrong, users can submit a report that the VPT team can investigate from the admin panel.

Overview

The query logging & reporting system works in two steps:

  1. Capture — the server records every API request and returns a X-VPT-Log-Id header in every response. Your application should read and store this value.
  2. Report — when a user encounters a problem, your application calls reportQuery with the stored log ID and a short description. The VPT team is notified by email and can review the full request/response trace in the admin panel.
Authentication

reportQuery requires the user to be logged in. The request must include the user's JWT as a Bearer token in the Authorization header. api_key is not accepted for this endpoint.

Unique Log ID
Every response carries an X-VPT-Log-Id header linking the interaction to the server-side trace.
User Reports
Users can flag a specific call with a severity level and description. The log entry is preserved until the report is resolved.
Auto-redaction
Sensitive fields (dev_key, password, tokens) are automatically redacted from stored request bodies.

Log ID Header

Every monitored API response includes the following HTTP header:

Response Header 
X-VPT-Log-Id: 12345

Read this value from every response and store it alongside the result shown to the user. If the user later wants to report an issue, pass it as data.logId in the reportQuery call.

Retention window

Log entries are automatically deleted after 3 days unless they have been reported. Once a user submits a report, the entry is kept indefinitely until an admin resolves it. Avoid storing log IDs for longer than 3 days before presenting the report option to the user.

reportQuery

Submit a user-initiated issue report against a previously logged API call.

POST /api

Headers

Header Required Description
Authorization Required Bearer <jwt> — the user's JWT obtained from the login endpoint
Content-Type Required application/json

Request Body

JSON 
{
  "query":   "reportQuery",
  "dev_key": "your_developer_key",
  "data": {
    "logId":       12345,
    "severity":    "MEDIUM",
    "description": "The takeoff result was missing the climb gradient value."
  }
}

Parameters

Parameter Type Required Description
query string Required Must be "reportQuery"
dev_key string Required Your developer key
data object
logId integer Required The value from the X-VPT-Log-Id response header of the call being reported
severity string Required LOW, MEDIUM, or HIGH
description string Required User's description of the problem (max 4 000 characters)

Success Response

200 OK 
{
  "Success":  true,
  "ReportId": 42
}

Return ReportId to the user as a reference number they can quote to the support team.

Error Responses

Condition Error message
Missing or invalid Bearer token Authentication required. Provide a valid Bearer token in the Authorization header.
logId not found or belongs to another user Log entry not found or does not belong to this user.
Invalid severity value Invalid severity. Use LOW, MEDIUM, or HIGH.
description is empty Description is required.

Full Example

JavaScript 
// After every API call, store the log ID
const logId = parseInt(response.headers.get('X-VPT-Log-Id') ?? '0', 10);

// When the user submits a report
const reportResponse = await fetch('https://api.virtualperformancetool.com/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${jwt}`   // user JWT from login
  },
  body: JSON.stringify({
    query:   'reportQuery',
    dev_key: 'your_developer_key',
    data: {
      logId,
      severity:    'MEDIUM',
      description: 'The takeoff result was missing the climb gradient value.'
    }
  })
});

const result = await reportResponse.json();
if (result.Success) {
  showToUser(`Report submitted. Reference: #${result.ReportId}`);
}

Retention & Privacy

Log retention

Table Default retention If reported
api_query_logs 3 days Kept until report is resolved or dismissed by an admin
calculation_logs 30 days Kept until report is resolved or dismissed by an admin

Stored data & redaction

The following fields are automatically redacted from stored request bodies before writing to the database:

  • dev_key
  • api_key
  • password
  • Any field whose name contains token

Request and response bodies larger than 1 MB are truncated.

Integration Tips

Suggested UX pattern
  1. On every API response, read and store the X-VPT-Log-Id header value alongside the displayed result.
  2. Show a discreet "Report an issue" action near the result (button, menu item, or long-press gesture).
  3. When tapped, present a small form with:
    • Severity — LOW / MEDIUM / HIGH (e.g. a segmented control)
    • Description — free-text field (max 4 000 chars)
  4. POST reportQuery with the stored logId and the user's input.
  5. Display the returned ReportId to the user as a support reference number.
User must be logged in

The report button should only be visible when a user is authenticated, as the endpoint requires a valid Bearer token. For anonymous contexts, consider directing users to the support page instead.