(GET) Get analytics

Retrieve click analytics and performance data for your links. Filter by link, partner, or date range.

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	Description
`linkId` (query)	string (UUID)	No	Filter analytics by specific link ID. Returns click data only for the specified link.
`partnerId` (query)	string (UUID)	No	Filter analytics by partner ID. Returns click data for all links associated with the specified partner.
`startDate` (query)	string (UTC ISO 8601)	No	Start date for the date range filter. Must be a UTC timestamp with trailing `Z` (e.g., "2024-01-01T00:00:00Z"). Offsets such as `+03:00` are rejected.
`endDate` (query)	string (UTC ISO 8601)	No	End date for the date range filter. Must be a UTC timestamp with trailing `Z` (e.g., "2024-01-31T23:59:59Z"). Offsets such as `+03:00` are rejected.
`take` (query)	number	No	Number of results to return (default: 50, min: 1, max: 5,000). Use pagination to retrieve large datasets efficiently.
`skip` (query)	number	No	Number of results to skip for pagination (default: 0, min: 0). Use with take to implement pagination.
`sort` (query)	string	No	Sort order by createdAt: "asc" for oldest clicks first, "desc" for newest clicks first (default: "desc").

Request Limits

The `take` parameter supports values from 1 to 5,000. Requests above 5,000 are rejected.

Retention Window

Results are clamped to your workspace plan retention window and to the current server time. If `startDate` is earlier than the retention window, the effective start is moved forward. If `endDate` is in the future, the effective end is the current server time.

Examples

Request cURL

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 <API_KEY>"

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 <API_KEY>'
	}
});
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": "2f4b1bf7-e58e-48c7-b6e6-ae0615da133d",
		"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",
		"expired": false,
		"secured": false,
		"scanned": false,
		"geoTargeted": false,
		"iosTargeted": false,
		"androidTargeted": false,
		"origin": null,
		"pathname": null,
		"search": null,
		"browserLanguageCode": null,
		"browserLanguageRegion": null,
		"browserName": "Chrome",
		"browserVersion": "120.0",
		"osName": "Windows",
		"osVersion": "10",
		"deviceVendor": null,
		"deviceModel": null,
		"deviceType": "desktop",
		"ipAddress": null,
		"continent": null,
		"country": "United States",
		"countryCode": "US",
		"region": null,
		"city": "New York",
		"district": null,
		"zip": null,
		"latitude": null,
		"longitude": null,
		"mobile": false,
		"proxy": false,
		"hosting": false,
		"createdAt": "2024-01-01T00:00:00Z"
	}
]