Query Clics analytics stats via the REST API

Query metrics and dimensions. For KPI queries with include.previous_period enabled, the response includes comparison with previous-period values and percentage changes.

POST/v1/query

Authorization

AuthorizationBearer token (API key) · headerrequired

Request body

requiredapplication/json

project_idstringrequired

Clics project ID.

min length 1

domainstring

Optional domain filter (e.g. `example.com`). Schemes like `https://`, paths, and ports are stripped. Omit to query all production domains for the project (localhost/dev traffic is excluded by default). Pass "localhost" to query development traffic only.

min length 1

timezonestring

IANA timezone used for calendar period boundaries and daily buckets. Defaults to `UTC`.

default: "UTC"

Allowed:Africa/AbidjanAfrica/AccraAfrica/Addis_AbabaAfrica/AlgiersAfrica/AsmeraAfrica/BamakoAfrica/BanguiAfrica/BanjulAfrica/BissauAfrica/BlantyreAfrica/BrazzavilleAfrica/BujumburaAfrica/CairoAfrica/CasablancaAfrica/CeutaAfrica/ConakryAfrica/DakarAfrica/Dar_es_SalaamAfrica/DjiboutiAfrica/DoualaAfrica/El_AaiunAfrica/FreetownAfrica/GaboroneAfrica/HarareAfrica/JohannesburgAfrica/JubaAfrica/KampalaAfrica/KhartoumAfrica/KigaliAfrica/KinshasaAfrica/LagosAfrica/LibrevilleAfrica/LomeAfrica/LuandaAfrica/LubumbashiAfrica/LusakaAfrica/MalaboAfrica/MaputoAfrica/MaseruAfrica/MbabaneAfrica/MogadishuAfrica/MonroviaAfrica/NairobiAfrica/NdjamenaAfrica/NiameyAfrica/NouakchottAfrica/OuagadougouAfrica/Porto-NovoAfrica/Sao_TomeAfrica/TripoliAfrica/TunisAfrica/WindhoekAmerica/AdakAmerica/AnchorageAmerica/AnguillaAmerica/AntiguaAmerica/AraguainaAmerica/Argentina/La_RiojaAmerica/Argentina/Rio_GallegosAmerica/Argentina/SaltaAmerica/Argentina/San_JuanAmerica/Argentina/San_LuisAmerica/Argentina/TucumanAmerica/Argentina/UshuaiaAmerica/ArubaAmerica/AsuncionAmerica/BahiaAmerica/Bahia_BanderasAmerica/BarbadosAmerica/BelemAmerica/BelizeAmerica/Blanc-SablonAmerica/Boa_VistaAmerica/BogotaAmerica/BoiseAmerica/Buenos_AiresAmerica/Cambridge_BayAmerica/Campo_GrandeAmerica/CancunAmerica/CaracasAmerica/CatamarcaAmerica/CayenneAmerica/CaymanAmerica/ChicagoAmerica/ChihuahuaAmerica/Ciudad_JuarezAmerica/Coral_HarbourAmerica/CordobaAmerica/Costa_RicaAmerica/CoyhaiqueAmerica/CrestonAmerica/CuiabaAmerica/CuracaoAmerica/DanmarkshavnAmerica/DawsonAmerica/Dawson_CreekAmerica/DenverAmerica/DetroitAmerica/DominicaAmerica/EdmontonAmerica/EirunepeAmerica/El_SalvadorAmerica/Fort_NelsonAmerica/FortalezaAmerica/Glace_BayAmerica/GodthabAmerica/Goose_BayAmerica/Grand_TurkAmerica/GrenadaAmerica/GuadeloupeAmerica/GuatemalaAmerica/GuayaquilAmerica/GuyanaAmerica/HalifaxAmerica/HavanaAmerica/HermosilloAmerica/Indiana/KnoxAmerica/Indiana/MarengoAmerica/Indiana/PetersburgAmerica/Indiana/Tell_CityAmerica/Indiana/VevayAmerica/Indiana/VincennesAmerica/Indiana/WinamacAmerica/IndianapolisAmerica/InuvikAmerica/IqaluitAmerica/JamaicaAmerica/JujuyAmerica/JuneauAmerica/Kentucky/MonticelloAmerica/KralendijkAmerica/La_PazAmerica/LimaAmerica/Los_AngelesAmerica/LouisvilleAmerica/Lower_PrincesAmerica/MaceioAmerica/ManaguaAmerica/ManausAmerica/MarigotAmerica/MartiniqueAmerica/MatamorosAmerica/MazatlanAmerica/MendozaAmerica/MenomineeAmerica/MeridaAmerica/MetlakatlaAmerica/Mexico_CityAmerica/MiquelonAmerica/MonctonAmerica/MonterreyAmerica/MontevideoAmerica/MontserratAmerica/NassauAmerica/New_YorkAmerica/NomeAmerica/NoronhaAmerica/North_Dakota/BeulahAmerica/North_Dakota/CenterAmerica/North_Dakota/New_SalemAmerica/OjinagaAmerica/PanamaAmerica/ParamariboAmerica/PhoenixAmerica/Port-au-PrinceAmerica/Port_of_SpainAmerica/Porto_VelhoAmerica/Puerto_RicoAmerica/Punta_ArenasAmerica/Rankin_InletAmerica/RecifeAmerica/ReginaAmerica/ResoluteAmerica/Rio_BrancoAmerica/SantaremAmerica/SantiagoAmerica/Santo_DomingoAmerica/Sao_PauloAmerica/ScoresbysundAmerica/SitkaAmerica/St_BarthelemyAmerica/St_JohnsAmerica/St_KittsAmerica/St_LuciaAmerica/St_ThomasAmerica/St_VincentAmerica/Swift_CurrentAmerica/TegucigalpaAmerica/ThuleAmerica/TijuanaAmerica/TorontoAmerica/TortolaAmerica/VancouverAmerica/WhitehorseAmerica/WinnipegAmerica/YakutatAntarctica/CaseyAntarctica/DavisAntarctica/DumontDUrvilleAntarctica/MacquarieAntarctica/MawsonAntarctica/McMurdoAntarctica/PalmerAntarctica/RotheraAntarctica/SyowaAntarctica/TrollAntarctica/VostokArctic/LongyearbyenAsia/AdenAsia/AlmatyAsia/AmmanAsia/AnadyrAsia/AqtauAsia/AqtobeAsia/AshgabatAsia/AtyrauAsia/BaghdadAsia/BahrainAsia/BakuAsia/BangkokAsia/BarnaulAsia/BeirutAsia/BishkekAsia/BruneiAsia/CalcuttaAsia/ChitaAsia/ColomboAsia/DamascusAsia/DhakaAsia/DiliAsia/DubaiAsia/DushanbeAsia/FamagustaAsia/GazaAsia/HebronAsia/Hong_KongAsia/HovdAsia/IrkutskAsia/JakartaAsia/JayapuraAsia/JerusalemAsia/KabulAsia/KamchatkaAsia/KarachiAsia/KatmanduAsia/KhandygaAsia/KrasnoyarskAsia/Kuala_LumpurAsia/KuchingAsia/KuwaitAsia/MacauAsia/MagadanAsia/MakassarAsia/ManilaAsia/MuscatAsia/NicosiaAsia/NovokuznetskAsia/NovosibirskAsia/OmskAsia/OralAsia/Phnom_PenhAsia/PontianakAsia/PyongyangAsia/QatarAsia/QostanayAsia/QyzylordaAsia/RangoonAsia/RiyadhAsia/SaigonAsia/SakhalinAsia/SamarkandAsia/SeoulAsia/ShanghaiAsia/SingaporeAsia/SrednekolymskAsia/TaipeiAsia/TashkentAsia/TbilisiAsia/TehranAsia/ThimphuAsia/TokyoAsia/TomskAsia/UlaanbaatarAsia/UrumqiAsia/Ust-NeraAsia/VientianeAsia/VladivostokAsia/YakutskAsia/YekaterinburgAsia/YerevanAtlantic/AzoresAtlantic/BermudaAtlantic/CanaryAtlantic/Cape_VerdeAtlantic/FaeroeAtlantic/MadeiraAtlantic/ReykjavikAtlantic/South_GeorgiaAtlantic/St_HelenaAtlantic/StanleyAustralia/AdelaideAustralia/BrisbaneAustralia/Broken_HillAustralia/DarwinAustralia/EuclaAustralia/HobartAustralia/LindemanAustralia/Lord_HoweAustralia/MelbourneAustralia/PerthAustralia/SydneyEurope/AmsterdamEurope/AndorraEurope/AstrakhanEurope/AthensEurope/BelgradeEurope/BerlinEurope/BratislavaEurope/BrusselsEurope/BucharestEurope/BudapestEurope/BusingenEurope/ChisinauEurope/CopenhagenEurope/DublinEurope/GibraltarEurope/GuernseyEurope/HelsinkiEurope/Isle_of_ManEurope/IstanbulEurope/JerseyEurope/KaliningradEurope/KievEurope/KirovEurope/LisbonEurope/LjubljanaEurope/LondonEurope/LuxembourgEurope/MadridEurope/MaltaEurope/MariehamnEurope/MinskEurope/MonacoEurope/MoscowEurope/OsloEurope/ParisEurope/PodgoricaEurope/PragueEurope/RigaEurope/RomeEurope/SamaraEurope/San_MarinoEurope/SarajevoEurope/SaratovEurope/SimferopolEurope/SkopjeEurope/SofiaEurope/StockholmEurope/TallinnEurope/TiraneEurope/UlyanovskEurope/VaduzEurope/VaticanEurope/ViennaEurope/VilniusEurope/VolgogradEurope/WarsawEurope/ZagrebEurope/ZurichIndian/AntananarivoIndian/ChagosIndian/ChristmasIndian/CocosIndian/ComoroIndian/KerguelenIndian/MaheIndian/MaldivesIndian/MauritiusIndian/MayotteIndian/ReunionPacific/ApiaPacific/AucklandPacific/BougainvillePacific/ChathamPacific/EasterPacific/EfatePacific/EnderburyPacific/FakaofoPacific/FijiPacific/FunafutiPacific/GalapagosPacific/GambierPacific/GuadalcanalPacific/GuamPacific/HonoluluPacific/KiritimatiPacific/KosraePacific/KwajaleinPacific/MajuroPacific/MarquesasPacific/MidwayPacific/NauruPacific/NiuePacific/NorfolkPacific/NoumeaPacific/Pago_PagoPacific/PalauPacific/PitcairnPacific/PonapePacific/Port_MoresbyPacific/RarotongaPacific/SaipanPacific/TahitiPacific/TarawaPacific/TongatapuPacific/TrukPacific/WakePacific/WallisUTC

metricsstring[]required

Metrics to compute. KPI/time-series: visitors, visits, pageviews, bounce_rate, visit_duration, views_per_visit. Breakdown: visitors, pageviews, conversion_rate, events. Realtime supports visitors only.

min items 1

date_rangestring | any[]required

Dashboard period preset (last24h, last7days, last30days, last3months, last12months, monthToDate, quarterToDate, yearToDate, allTime) or custom ISO8601 start/end pair.

Show properties

Any of:

string

string

any[]

Array of any

dimensionsstring[]

Optional grouping. Use one time dimension, or up to two breakdown dimensions. Event name, outbound URL, and AI provider dimensions are supported alongside dashboard dimensions.

filtersany[][]

Filter expressions. Supported dimensions are listed in the schema.

order_byany[][] | null

Optional sort order. Omit this field when sorting is not needed. Each entry is [field, direction].

includeobject

Show properties

previous_periodboolean

total_rowsboolean

paginationobject

Show properties

limitinteger

min 1 · max 1000

offsetinteger

min 0

Responses

200Query results.

resultsobject[]required

Show properties

Array of object

metricsnumber[]required

metric_valuesobjectrequired

dimensionsstring | number[]required

Show properties

Array of string | number

Any of:

string

string

number

number

dimension_valuesobjectrequired

metaobjectrequired

comparisonobject

Previous-period metric values and percentage change. Present only when include.previous_period is true for a KPI query.

Show properties

previous_metric_valuesobjectrequired

change_percentobjectrequired

queryStatsQueryRequestrequired

Show properties

project_idstringrequired

Clics project ID.

min length 1

domainstring

min length 1

timezonestring

IANA timezone used for calendar period boundaries and daily buckets. Defaults to `UTC`.

default: "UTC"

metricsstring[]required

min items 1

date_rangestring | any[]required

Dashboard period preset (last24h, last7days, last30days, last3months, last12months, monthToDate, quarterToDate, yearToDate, allTime) or custom ISO8601 start/end pair.

Show properties

Any of:

string

string

any[]

Array of any

dimensionsstring[]

Optional grouping. Use one time dimension, or up to two breakdown dimensions. Event name, outbound URL, and AI provider dimensions are supported alongside dashboard dimensions.

filtersany[][]

Filter expressions. Supported dimensions are listed in the schema.

order_byany[][] | null

Optional sort order. Omit this field when sorting is not needed. Each entry is [field, direction].

includeobject

Show properties

previous_periodboolean

total_rowsboolean

paginationobject

Show properties

limitinteger

min 1 · max 1000

offsetinteger

min 0

400Invalid query.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

401Missing or invalid API key.

403Paid plan required.

503Upstream dependency unavailable.

Request

curl -X POST "https://api.clics.dev/v1/query" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "project_id": "k17abc123",
  "domain": "example.com",
  "timezone": "Europe/London",
  "metrics": [
    "visitors",
    "pageviews",
    "bounce_rate"
  ],
  "date_range": "last7days",
  "dimensions": [
    "visit:country"
  ],
  "filters": [
    [
      "is",
      "visit:country",
      [
        "US",
        "FR"
      ]
    ]
  ],
  "order_by": [
    [
      "visitors",
      "desc"
    ]
  ],
  "include": {
    "previous_period": true,
    "total_rows": true
  },
  "pagination": {
    "limit": 0,
    "offset": 0
  }
}'

const response = await fetch("https://api.clics.dev/v1/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "project_id": "k17abc123",
  "domain": "example.com",
  "timezone": "Europe/London",
  "metrics": [
    "visitors",
    "pageviews",
    "bounce_rate"
  ],
  "date_range": "last7days",
  "dimensions": [
    "visit:country"
  ],
  "filters": [
    [
      "is",
      "visit:country",
      [
        "US",
        "FR"
      ]
    ]
  ],
  "order_by": [
    [
      "visitors",
      "desc"
    ]
  ],
  "include": {
    "previous_period": true,
    "total_rows": true
  },
  "pagination": {
    "limit": 0,
    "offset": 0
  }
})
});

import requests

response = requests.post(
    "https://api.clics.dev/v1/query",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "project_id": "k17abc123",
  "domain": "example.com",
  "timezone": "Europe/London",
  "metrics": [
    "visitors",
    "pageviews",
    "bounce_rate"
  ],
  "date_range": "last7days",
  "dimensions": [
    "visit:country"
  ],
  "filters": [
    [
      "is",
      "visit:country",
      [
        "US",
        "FR"
      ]
    ]
  ],
  "order_by": [
    [
      "visitors",
      "desc"
    ]
  ],
  "include": {
    "previous_period": True,
    "total_rows": True
  },
  "pagination": {
    "limit": 0,
    "offset": 0
  }
},
)

Response

{
  "results": [
    {
      "metrics": [
        0
      ],
      "metric_values": {},
      "dimensions": [
        "string"
      ],
      "dimension_values": {}
    }
  ],
  "meta": {},
  "comparison": {
    "previous_metric_values": {},
    "change_percent": {}
  },
  "query": {
    "project_id": "k17abc123",
    "domain": "example.com",
    "timezone": "Europe/London",
    "metrics": [
      "visitors",
      "pageviews",
      "bounce_rate"
    ],
    "date_range": "last7days",
    "dimensions": [
      "visit:country"
    ],
    "filters": [
      [
        "is",
        "visit:country",
        [
          "US",
          "FR"
        ]
      ]
    ],
    "order_by": [
      [
        "visitors",
        "desc"
      ]
    ],
    "include": {
      "previous_period": true,
      "total_rows": true
    },
    "pagination": {
      "limit": 0,
      "offset": 0
    }
  }
}