Activities API Documentation

Overview

The Activities API provides event tracking data for short URLs. It allows retrieving visitor activity information based on various filters such as URL slug, domain, and date ranges.

Endpoint

GET /api/activities

Request Parameters

Parameter	Type	Required	Description
`slug`	string	No*	The short URL slug to filter events by
`domain`	string	No*	The domain to filter events by
`startTime`	string	No*	Start time for date range filter (ISO format)
`endTime`	string	No*	End time for date range filter (ISO format)
`page`	integer	No	Page number for pagination (default: 1)
`pageSize`	integer	No	Number of records per page (default: 50)
`format`	string	No	Response format, set to 'csv' for CSV output (default: JSON)

* Either slug+domain combination OR at least one of startTime/endTime must be provided.

Response Formats

JSON Format (Default)

JSON responses include the following structure:

{
  "success": true,
  "data": [
    {
      "id": "event-id",
      "type": "event-type",
      "time": "timestamp",
      "visitor": {
        "id": "visitor-id",
        "ipAddress": "ip-address",
        "userAgent": "user-agent-string",
        "referrer": "referrer-url"
      },
      "device": {
        "type": "device-type",
        "browser": "browser-name",
        "os": "operating-system"
      },
      "location": {
        "country": "country-code",
        "city": "city-name"
      },
      "link": {
        "id": "link-id",
        "slug": "link-slug",
        "originalUrl": "original-url",
        "label": "link-label",
        "tags": ["tag1", "tag2"]
      },
      "utm": {
        "source": "utm-source",
        "medium": "utm-medium",
        "campaign": "utm-campaign",
        "term": "utm-term",
        "content": "utm-content"
      }
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "pageSize": 50
  }
}

In case of an error:

{
  "success": false,
  "data": null,
  "error": "Error message description"
}

CSV Format

When format=csv is specified, the response is returned as plain text in CSV format with the following columns:

time: Timestamp of the event
activity: Type of activity/event
campaign: UTM campaign value (defaults to "demo" if not found)
clientId: Visitor ID
originPath: Original request path or referrer URL

Examples

Get activities for a specific short URL

GET /api/activities?slug=promo123&domain=googleads.link

Get activities within a date range

GET /api/activities?startTime=2023-06-01T00:00:00Z&endTime=2023-06-30T23:59:59Z

Get events as CSV

GET /api/activities?slug=promo123&domain=googleads.link&format=csv

Pagination example

GET /api/activities?slug=promo123&domain=googleads.link&page=2&pageSize=20

Error Codes

Status Code	Description
400	Missing required parameters
500	Server error while processing the request

Notes

For privacy and security reasons, some fields may be omitted or anonymized based on user settings.
The CSV format is optimized for easy import into spreadsheet applications.
When using the CSV format, the response is returned as plain text rather than a downloadable file.