> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Format

> Understanding report response structures and data interpretation

## 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.

<Note>
  Other endpoints like `/v1/org/*` and `/v1/prompts/*` use standard JSON object
  structures that are documented in the OpenAPI reference.
</Note>

## Report Response Structure

All report endpoints return data in this optimized format:

```json theme={null}
{
  "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:

| Field        | Description                                               |
| ------------ | --------------------------------------------------------- |
| `query`      | Your exact request parameters echoed back                 |
| `total_rows` | Total 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:

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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 }]

  ```

  ```python Python theme={null}
  def process_report_data(response):
      """Convert array-based response to dict format"""
      query_info = response['info']['query']
      dim_names = query_info['dimensions']
      metric_names = query_info['metrics']

      results = []
      for row in response['data']:
          result = {}

          # Map dimensions
          for i, name in enumerate(dim_names):
              result[name] = row['dimensions'][i]

          # Map metrics
          for i, name in enumerate(metric_names):
              result[name] = row['metrics'][i]

          results.append(result)

      return results

  # Usage
  processed_data = process_report_data(api_response)
  # Result: [{"hostname": "example.com", "path": "/some/path", "date": "2023-10-01", "count": 10, "share_of_voice": 0.05}]
  ```

  ```php PHP theme={null}
  function processReportData($response) {
      $queryInfo = $response['info']['query'];
      $dimNames = $queryInfo['dimensions'];
      $metricNames = $queryInfo['metrics'];

      $results = [];
      foreach ($response['data'] as $row) {
          $result = [];

          // Map dimensions
          foreach ($dimNames as $index => $name) {
              $result[$name] = $row['dimensions'][$index];
          }

          // Map metrics
          foreach ($metricNames as $index => $name) {
              $result[$name] = $row['metrics'][$index];
          }

          $results[] = $result;
      }

      return $results;
  }
  ```
</CodeGroup>

## 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.