Skip to main content

​
Overview

Report endpoints (/v1/reports/*) use a specialized array-based response format to optimize performance and reduce payload size. This guide explains how to interpret these responses.
Other endpoints like /v1/org/* and /v1/prompts/* use standard JSON object structures that are documented in the OpenAPI reference.

​
Report Response Structure

All report endpoints return data in this optimized format: 
{
  "data": [
    {
      "dimensions": ["example.com", "/some/path", "2023-10-01"],
      "metrics": [10, 0.05]
    },
    {
      "dimensions": ["another-site.com", "/different/path", "2023-10-02"],
      "metrics": [15, 0.08]
    }
  ],
  "info": {
    "query": {
      "date_interval": "day",
      "dimensions": ["hostname", "path", "date"],
      "filters": [
        {
          "field": "hostname",
          "operator": "in",
          "value": ["example.com", "another-site.com"]
        }
      ],
      "metrics": ["count", "share_of_voice"]
    },
    "total_rows": 200
  }
}

​
Interpreting Report Data

​
Array Position Mapping

The key to understanding report responses is that array positions correspond exactly to your request parameters:

​
Dimensions Array

Values map to the order of dimensions in your request:
  • dimensions[0] → First dimension requested (hostname)
  • dimensions[1] → Second dimension requested (path)
  • dimensions[2] → Third dimension requested (date)

​
Metrics Array

Values map to the order of metrics in your request:
  • metrics[0] → First metric requested (count)
  • metrics[1] → Second metric requested (share_of_voice)

​
Example Mapping

For the first result object above:
  • Hostname: dimensions[0] = “example.com”
  • Path: dimensions[1] = “/some/path”
  • Date: dimensions[2] = “2023-10-01”
  • Count: metrics[0] = 10
  • Share of Voice: metrics[1] = 0.05

​
Info Object

The info object provides metadata about your query:
FieldDescription
queryYour exact request parameters echoed back
total_rowsTotal number of results available (useful for pagination)

​
Working with Report Responses

​
Processing Data

Example of converting the array format to a more traditional object structure: 
// Process report response
const processReportData = (response) => {
  const { dimensions: dimNames, metrics: metricNames } = response.info.query;
  
  return response.data.map(row => {
    const result = {};
    
    // Map dimensions
    dimNames.forEach((name, index) => {
      result[name] = row.dimensions[index];
    });
    
    // Map metrics
    metricNames.forEach((name, index) => {
      result[name] = row.metrics[index];
    });
    
    return result;
  });
};

// Usage
const processedData = processReportData(apiResponse);
// Result: [{ hostname: "example.com", path: "/some/path", date: "2023-10-01", count: 10, share_of_voice: 0.05 }]

​
Best Practices

  1. Always use the info.query object to understand the structure of your response data
  2. Process responses programmatically using the mapping examples above rather than hardcoding array positions
  3. Handle pagination using the total_rows field to determine if more data is available
  4. Monitor rate limit headers to avoid hitting API limits
  5. Validate your request parameters match the expected dimensions and metrics for your use case

​
Need Help?

If you encounter unexpected response formats or need clarification on specific report responses, contact our support team for assistance.