---
title: "Serql concepts and data model"
description: "Definitions of the objects the Serql API and MCP server work with: properties, Google accounts, segments, topic clusters, branded keywords, annotations, tags, share links, and team roles."
canonical: https://www.serql.io/docs/concepts
markdown: https://www.serql.io/docs/concepts.md
last-updated: 2026-09-14
section: docs
site: "Serql"
llms: https://www.serql.io/llms.txt
---

# Serql concepts and data model

## Google account

A Google identity connected through OAuth with read-only Search Console scope. One user can connect several Google accounts; tokens are AES-encrypted at rest.

## Property

A Search Console property (URL-prefix or domain property) discovered from a connected Google account. Properties are **tracked** explicitly; only tracked properties appear in the API and count toward plan limits. Each property has a UUID `id`, a `siteUrl` (for example `sc-domain:example.com`), and a permission level mirrored from Google.

## Metrics

Clicks, impressions, CTR (0-1 in raw rows, percent in aggregated series), and average position, exactly as Search Console reports them, for a `searchType` of web, discover, googleNews, image, or video.

## Dimensions and filters

Query, page, country (ISO 3166-1 alpha-3), device, date, and search appearance. Filters are `{ dimension, operator, value, logic? }` conditions (`contains`, `not_contains`, `equals`, `matches_regex`, `or_list`) combined with AND by default.

## Classification

Any way of splitting the dataset:

- **Branded keywords** — a per-property list of brand terms; `classification=branded|nonBranded`.
- **Segment** — a saved rule set over queries and pages (contains, regex, equals, starts with…), evaluated live; `classification=segment:<uuid>`.
- **Topic cluster** — a named set of terms grouping queries by topic; `classification=topicCluster:<uuid>`.

## Annotation

A dated note (title, description, optional affected segments/pages) drawn on performance charts. Google's confirmed core updates are provided automatically as separate `coreUpdates` entries.

## Tag

A user-level label applied to properties on the portfolio dashboard (client, region, business unit).

## Share link

A revocable, unguessable token that exposes a property's performance view read-only at `/share/{token}` and `GET /api/share/{token}/performance`. Share links are rate limited and never expose account data.

## Team membership and roles

Property-level grants: **owner** (the Google account holder), **admin**, **member**, **viewer**. Read endpoints need viewer; annotations, segments, and clusters need member; share links and team management need admin. Sponsored seats count toward the billing owner's plan.

## Entitlement

What the caller's plan allows (seat count, tracked-property limit). Self-hosted deployments use the "unlimited" provider; the hosted service uses Stripe subscriptions. Endpoints return `402` with `code: "subscription_required"` when an entitlement is missing.