canonical: https://jentic.com/apis/gosquared.com/gosquared

# GoSquared Tracking API

Jentic publishes the only available OpenAPI specification for GoSquared Tracking API, keeping it validated and agent-ready. The GoSquared Tracking API records pageviews and custom events from any platform or device, with hooks into GoSquared's People CRM for visitor identification. The two server-side endpoints (POST /event and POST /pageview) accept a project key in the query string, eliminating client-side SDK weight and enabling tracking from backends, CLI tools, IoT devices, and AI agents.

## For AI agents

Send server-side pageview and event records to GoSquared real-time analytics with visitor identification across any device or runtime.

## Scope

Does not handle dashboards, cohort queries, or message sending - use for sending pageview and event records into GoSquared only.

## Capabilities

- Record a pageview with URL, referrer, and visitor identifier
- Send a custom event with arbitrary properties for product analytics
- Identify a visitor by email or external_id to feed the People CRM
- Track activity from server-side runtimes that cannot ship a JS SDK
- Instrument backends, CLIs, and IoT devices with the same project key
- Forward events from a downstream pipeline (Segment, Kafka) into GoSquared
- Capture conversion and signup events for funnel analysis

## Use cases

### Server-Side Event Tracking

Send conversion, signup, and purchase events from your backend or worker fleet to GoSquared without depending on a browser SDK. POST /event with a project key, person identifier, event name, and JSON properties to record activity even when the user has ad-blockers enabled or the action happens off-page.

Example prompt: POST /event with name 'signup-completed', person email user@example.com, properties {'plan':'pro','utm_source':'launch'} to the GoSquared project.

### Real-Time Pageview Logging

Log a pageview every time a server-rendered route is hit so the GoSquared real-time dashboard reflects traffic regardless of client environment. This pattern is useful for SSR sites where the JS SDK loads slowly, for CLI usage tracking, and for embedded experiences that lack a DOM altogether.

Example prompt: POST /pageview with url 'https://example.com/dashboard', title 'Dashboard', and the visitor's anonymous_id captured from the session cookie.

### Pipeline Replay into GoSquared

Forward events from an existing data pipeline (Segment, Kafka, custom warehouse export) into GoSquared so the marketing and product teams can keep using the GoSquared dashboard. The two-endpoint surface keeps the integration small and durable, and GoSquared handles deduplication and rate limiting on the server side.

Example prompt: Read events from the kafka topic 'product-events' and POST each one to /event with the GoSquared project key, mapping pipeline fields to the expected payload.

### AI Agent Telemetry

An AI agent emits its own usage telemetry to GoSquared by calling /event with structured properties such as tool name, latency, and outcome. Through Jentic, the agent discovers the operation by intent and uses a vault-stored project key, so the analytics token is never exposed in agent prompts or logs.

Example prompt: Send a POST to /event named 'tool-called' with properties {'tool':'search','duration_ms':842,'success':true} so the team can see agent usage in real time.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/event` | Record a custom event |
| POST | `/pageview` | Record a pageview |

## Key resources

- **Events** — Send custom event records with arbitrary properties
- **Pageviews** — Record pageviews with URL, title, and visitor identifier

## Why Jentic

- **Setup:** Wiring the GoSquared Tracking API by hand means provisioning the project key, appending it as the api_key query parameter on every call, and matching event and pageview payloads against the api.gosquared.com/tracking/v1 host. Through Jentic you install once, import the GoSquared Tracking API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The GoSquared Tracking API carries its data in the request body, so you limit the agent to the operations it needs, such as sending an event or a pageview. You choose the operations it may call, so only the tracking calls you allow are available.
- **Credential handling:** Your GoSquared project key is stored once, encrypted, by your own Jentic One instance and injected at execution time as the api_key query parameter. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'track a signup event' or 'record a pageview', and Jentic returns the matching event or pageview operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Mixpanel** — Product analytics with funnels, retention, and cohort analysis
- **Amplitude** — Enterprise product analytics with experimentation tooling
- **Segment** — Customer data infrastructure that fans events out to many destinations

## FAQ

### Why is there no official OpenAPI spec for GoSquared Tracking API?

GoSquared does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call GoSquared Tracking API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the GoSquared Tracking API use?

The project key is passed in the request as a query parameter. Use the project token from your GoSquared dashboard. Through Jentic, the project key is stored in the encrypted vault and appended at execution time so it does not appear in agent prompts.

### Can I send custom event properties to GoSquared?

Yes. POST /event accepts a JSON body with name, person identifier, and a properties object containing arbitrary key-value pairs. Properties are indexed in GoSquared and can be filtered in the dashboard or used to drive triggers in GoSquared People.

### How do I record a pageview from a server-side renderer?

POST /pageview with the visitor identifier (anonymous or person id), the page URL, and optional title. This avoids the JS SDK on slow first-paint pages and ensures pageview counts even when ad-blockers run.

### How do I integrate the GoSquared Tracking API with an AI agent through Jentic?

Run pip install jentic, search 'track an event' to find POST /event, load the schema, and execute. Jentic appends the project key from the vault. Get started with Jentic One, the self-hosted execution layer.

### Can I limit what my agent is allowed to do with the GoSquared Tracking API?

Yes. Because you run Jentic One yourself, your own rules decide which of the GoSquared Tracking API operations your agent may call and which project key it uses. Since this API has only two operations, POST /event and POST /pageview, you can allow just the one the agent needs, for example letting it record events but not pageviews. The operations you do not permit are simply not available to the agent.