# Get analytics data

URL: /en/docs/api/v1/analytics/get
Last Updated: 2026-07-30T21:15:44.935Z

## Description
No description available.

## Available Actions
- Execute GET request
- View request parameters
- View response schema
- Get code examples
- Navigate to related topics
- View step-by-step instructions
- Get best practices

## Content
### GET /api/v1/analytics

**Get analytics data**

Retrieve comprehensive analytics data for the authenticated tenant including:
- Document view and download statistics with breakdowns
- Contact activity metrics and engagement data
- Access logs with recent user interactions
- Trend analysis with previous period comparisons

Data is automatically filtered by the authenticated tenant and supports
configurable time periods for analysis.

**Authentication:** Bearer token (`Authorization: Bearer <token>`)

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `period` | enum: 7d \| 30d \| 90d \| monthToDate \| lastMonth \| yearToDate \| lastYear | No | Time period for analytics data. Uses OpenPanel's native range values for optimal performance. When provided, this parameter is passed directly to OpenPanel as the 'range' parameter.  |
| `useRange` | boolean | No | Whether to use range parameter (recommended) or fall back to startDate/endDate.  |
| `startDate` | string (date) | No | Custom start date (YYYY-MM-DD format). Only used when useRange=false or when period is not a valid range. Overrides period parameter when used with endDate.  |
| `endDate` | string (date) | No | Custom end date (YYYY-MM-DD format). Only used when useRange=false or when period is not a valid range. Overrides period parameter when used with startDate.  |

**Responses:**

- `200` - Analytics data retrieved successfully
  - `documentStats` (array of DocumentStat (object), required): Document usage statistics broken down by document
    - `id` (string, required): Document identifier
    - `name` (string, required): Document display name
    - `views` (integer, required): Total number of document views in the period
    - `downloads` (integer, required): Total number of document downloads in the period
  - `contactStats` (array of ContactStat (object), required): Contact activity metrics and engagement data
    - `id` (string, required): Contact account identifier
    - `name` (string, required): Contact organization name
    - `documentsAccessed` (integer, required): Number of unique documents accessed by this contact
    - `lastAccess` (string (date-time), required): Timestamp of contact's last document access
  - `accessLogs` (array of AccessLog (object), required): Recent access logs with user interactions (max 50 entries)
    - `id` (string, required): Log entry identifier
    - `document` (string, required): Name of the accessed document
    - `contact` (string, required): Contact organization name
    - `user` (string, required): User email who performed the action
    - `action` (enum: View | Download, required): Type of action performed
    - `timestamp` (string (date-time), required): When the action occurred
  - `trends` (TrendsData (object), required): Trend analysis with previous period comparisons
    - `totalViews` (TrendData (object), required): Total document views trend analysis
      - `current` (number, required): Current period value
      - `previous` (number, required): Previous period value for comparison
      - `changePercent` (number, required): Percentage change from previous period (positive = increase, negative = decrease)
      - `trend` (enum: up | down | flat, required): Direction of the trend
    - `totalDownloads` (TrendData (object), required): Total document downloads trend analysis
      - `current` (number, required): Current period value
      - `previous` (number, required): Previous period value for comparison
      - `changePercent` (number, required): Percentage change from previous period (positive = increase, negative = decrease)
      - `trend` (enum: up | down | flat, required): Direction of the trend
    - `activeContacts` (TrendData (object), required): Active contacts trend analysis
      - `current` (number, required): Current period value
      - `previous` (number, required): Previous period value for comparison
      - `changePercent` (number, required): Percentage change from previous period (positive = increase, negative = decrease)
      - `trend` (enum: up | down | flat, required): Direction of the trend

  Example (Analytics with real data):
  
  ```json
  {
  "documentStats": [
    {
      "id": "doc-123",
      "name": "Privacy Policy",
      "views": 245,
      "downloads": 78
    },
    {
      "id": "doc-456",
      "name": "Terms of Service",
      "views": 189,
      "downloads": 42
    }
  ],
  "contactStats": [
    {
      "id": "cust-abc",
      "name": "Acme Inc",
      "documentsAccessed": 8,
      "lastAccess": "2024-03-15T14:32:00Z"
    },
    {
      "id": "cust-def",
      "name": "TechCorp",
      "documentsAccessed": 12,
      "lastAccess": "2024-03-17T09:45:00Z"
    }
  ],
  "accessLogs": [
    {
      "id": "log-001",
      "document": "SOC 2 Type II Report",
      "contact": "TechCorp",
      "user": "john.doe@techcorp.io",
      "action": "View",
      "timestamp": "2024-03-17T09:45:00Z"
    },
    {
      "id": "log-002",
      "document": "Penetration Test Results",
      "contact": "Acme Inc",
      "user": "security@acme.com",
      "action": "Download",
      "timestamp": "2024-03-15T14:32:00Z"
    }
  ],
  "trends": {
    "totalViews": {
      "current": 896,
      "previous": 800,
      "changePercent": 12,
      "trend": "up"
    },
    "totalDownloads": {
      "current": 361,
      "previous": 334,
      "changePercent": 8.1,
      "trend": "up"
    },
    "activeContacts": {
      "current": 3,
      "previous": 3,
      "changePercent": 0,
      "trend": "flat"
    }
  }
}
  ```

  Example (No analytics data available):
  
  ```json
  {
  "documentStats": [],
  "contactStats": [],
  "accessLogs": [],
  "trends": {
    "totalViews": {
      "current": 0,
      "previous": 0,
      "changePercent": 0,
      "trend": "flat"
    },
    "totalDownloads": {
      "current": 0,
      "previous": 0,
      "changePercent": 0,
      "trend": "flat"
    },
    "activeContacts": {
      "current": 0,
      "previous": 0,
      "changePercent": 0,
      "trend": "flat"
    }
  }
}
  ```
- `400` - Bad Request - invalid parameters
  - `error` (string)

  Example (Invalid period parameter):
  
  ```json
  {
  "error": "Invalid period. Must be one of: 7d, 30d, 90d, 1y"
}
  ```

  Example (Invalid date format):
  
  ```json
  {
  "error": "Invalid date format. Use YYYY-MM-DD format"
}
  ```

  Example (Missing endDate when startDate provided):
  
  ```json
  {
  "error": "endDate is required when startDate is provided"
}
  ```
- `401` - Unauthorized - authentication required
- `403` - Forbidden - insufficient permissions
- `500` - Internal server error - analytics service unavailable
  - `error` (string)

  Example (Analytics service error):
  
  ```json
  {
  "error": "Analytics service temporarily unavailable"
}
  ```

  Example (OpenPanel API error):
  
  ```json
  {
  "error": "Failed to retrieve analytics data from OpenPanel"
}
  ```

**Code samples:**

cURL:

```bash
curl -X GET "https://app.orbiqhq.com/api/v1/analytics?period=30d" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Accept: application/json"
```

JavaScript (fetch):

```javascript
const response = await fetch('/api/v1/analytics?period=30d', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Accept': 'application/json'
  }
});
const analyticsData = await response.json();
```

TypeScript (React Router):

```typescript
// In route loader
export const loader = async ({ request }: LoaderFunctionArgs) => {
  const url = new URL(request.url);
  const period = url.searchParams.get("period") || "7d";
  
  const response = await fetch(`/api/v1/analytics?period=${period}`, {
    headers: {
      Cookie: request.headers.get("Cookie") || "",
    },
  });
  
  return response.json();
};
```