--- **📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt) This is an individual endpoint documentation file. For the complete API reference, see the main documentation above. --- # (GET) Get analytics Retrieve click analytics and performance data for your links. Filter by link, partner, or date range. **Category:** Analytics ## Endpoint GET /api/analytics Retrieve click analytics and performance data for your links. Filter by link, partner, or date range to analyze specific segments of your traffic. Supports flexible filtering and pagination, making it easy to extract insights from large datasets. Results include detailed click information including device, location, browser, and UTM parameters. **Endpoint** ```text GET /api/analytics ``` ## Authentication Requires authentication with an API key that has the analyticsRead scope. ## Query Parameters | Parameter | Type | Required | Location | Description | |---|---|---|---|---| | linkId | string (UUID) | No | query | Filter analytics by specific link ID. Returns click data only for the specified link. | | partnerId | string (UUID) | No | query | Filter analytics by partner ID. Returns click data for all links associated with the specified partner. | | startDate | string (ISO 8601) | No | query | Start date for the date range filter. Must be in ISO 8601 format (e.g., "2024-01-01T00:00:00Z"). Only clicks on or after this date are returned. | | endDate | string (ISO 8601) | No | query | End date for the date range filter. Must be in ISO 8601 format (e.g., "2024-01-31T23:59:59Z"). Only clicks on or before this date are returned. | | take | number | No | query | Number of results to return (default: 50, min: 1, max: 10,000). Use pagination to retrieve large datasets efficiently. | | skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). Use with take to implement pagination. | | sort | string | No | query | Sort order by createdAt: "asc" for oldest clicks first, "desc" for newest clicks first (default: "desc"). | > **Warning: Request Limits** > The `take` parameter supports values from 1 to 10,000. Requests above 10,000 are rejected. ## Status Codes ### 200 Successfully retrieved analytics data. **Request** ```bash curl -X GET "https://hoko.to/api/analytics?linkId=550e8400-e29b-41d4-a716-446655440000&take=50" \ -H "Authorization: Bearer " ``` **Request** ```javascript const params = new URLSearchParams({ linkId: "550e8400-e29b-41d4-a716-446655440000", take: "50" }); const response = await fetch(`https://hoko.to/api/analytics?${params}`, { method: "GET", headers: { "Authorization": "Bearer " } }); const analytics = await response.json(); ``` **Response** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "linkId": "550e8400-e29b-41d4-a716-446655440000", "browserName": "Chrome", "deviceType": "desktop", "country": "United States", "createdAt": "2024-01-01T00:00:00Z" } ] ``` ### 400 Invalid query parameters (e.g., malformed dates or UUIDs). **Request** ```bash curl -X GET "https://hoko.to/api/analytics?startDate=invalid-date" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch("https://hoko.to/api/analytics?startDate=invalid-date", { method: "GET", headers: { "Authorization": "Bearer " } }); ``` **Response** ```json { "error": { "en": "Invalid request", "ar": "طلب غير صالح" } } ``` ### 401 Invalid or missing API key. **Request** ```bash curl -X GET "https://hoko.to/api/analytics" \ -H "Authorization: Bearer invalid_key" ``` **Request** ```javascript const response = await fetch("https://hoko.to/api/analytics", { method: "GET", headers: { "Authorization": "Bearer invalid_key" } }); ``` **Response** ```json { "error": { "en": "Invalid API key", "ar": "مفتاح API غير صالح" } } ``` ### 403 API key does not have the required analyticsRead scope. **Request** ```bash curl -X GET "https://hoko.to/api/analytics" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch("https://hoko.to/api/analytics", { method: "GET", headers: { "Authorization": "Bearer " } }); ``` **Response** ```json { "error": { "en": "Missing required scopes", "ar": "الصلاحيات المطلوبة مفقودة" }, "missingScopes": ["analyticsRead"] } ``` ### 429 Rate limit exceeded. Check X-RateLimit-* headers for details. **Request** ```bash curl -X GET "https://hoko.to/api/analytics" \ -H "Authorization: Bearer " ``` **Request** ```javascript const response = await fetch("https://hoko.to/api/analytics", { method: "GET", headers: { "Authorization": "Bearer " } }); ``` **Response** ```json { "error": { "en": "Rate limit exceeded", "ar": "تم تجاوز حد المعدل" }, "retryAfter": 60 } ``` ## Examples **Request** ```bash curl -X GET "https://hoko.to/api/analytics?linkId=550e8400-e29b-41d4-a716-446655440000&startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&take=50" \ -H "Authorization: Bearer " ``` **Request** ```javascript const params = new URLSearchParams({ linkId: "550e8400-e29b-41d4-a716-446655440000", startDate: "2024-01-01T00:00:00Z", endDate: "2024-01-31T23:59:59Z", take: "50" }); const response = await fetch(`https://hoko.to/api/analytics?${params}`, { method: "GET", headers: { "Authorization": "Bearer " } }); const analytics = await response.json(); ``` **Response** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "linkId": "550e8400-e29b-41d4-a716-446655440000", "partnerId": "550e8400-e29b-41d4-a716-446655440000", "visitorId": "visitor_123", "visitorSessionId": "session_123", "referrer": "https://google.com", "destination": "https://example.com", "shortId": "abc123", "utm": { "source": "google", "medium": "cpc", "campaign": "summer" }, "externalId": "ext_123", "tenantId": "tenant_123", "browserName": "Chrome", "browserVersion": "120.0", "osName": "Windows", "osVersion": "10", "deviceType": "desktop", "country": "United States", "countryCode": "US", "city": "New York", "createdAt": "2024-01-01T00:00:00Z" } ] ``` --- **Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)