{"openapi":"3.0.0","info":{"title":"Vemetric API","version":"1.0.0","description":"Privacy-first analytics API"},"components":{"schemas":{},"parameters":{}},"paths":{"/v1/project":{"get":{"summary":"Get project","description":"Returns the data of the project associated with the provided API key.","parameters":[{"schema":{"type":"string","description":"Bearer token for a project API key. This endpoint returns data for that project only.","example":"Bearer vem_abcdefghijklmnopqrstuvwxyz123456"},"required":true,"name":"authorization","in":"header"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"object","properties":{"id":{"type":"string","description":"Unique project identifier","example":"4232882524803099"},"name":{"type":"string","description":"Name of the project","example":"Vemetric"},"domain":{"type":"string","description":"Primary domain of the project","example":"vemetric.com"},"token":{"type":"string","description":"Public token used for tracking","example":"project_token_123"},"createdAt":{"type":"string","format":"date-time","description":"Project creation timestamp (ISO 8601)","example":"2026-02-07T12:00:00.000Z"},"firstEventAt":{"type":"string","nullable":true,"format":"date-time","description":"Timestamp of the first ingested event, if available (ISO 8601)","example":"2026-02-07T12:30:00.000Z"},"hasPublicDashboard":{"type":"boolean","description":"Whether the project has public dashboard access enabled","example":false},"excludedIps":{"type":"array","items":{"type":"string"},"description":"List of excluded IP Addresses","example":["127.0.0.1"]},"excludedCountries":{"type":"array","items":{"type":"string"},"description":"List of excluded countries as ISO 3166-1 alpha-2 codes","example":["DE","AT"]}},"required":["id","name","domain","token","createdAt","firstEventAt","hasPublicDashboard","excludedIps","excludedCountries"],"description":"Project data associated with the provided API key."}},"required":["project"]}}}},"400":{"description":"Bad request - invalid request payload or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Machine-readable validation error code."},"message":{"type":"string","description":"Human-readable validation summary."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Path to the invalid request field.","example":"groupBy.0"},"message":{"type":"string","description":"Validation error message for the field."}},"required":["field","message"]},"description":"Per-field validation issues."}},"required":["code","message","details"],"description":"Validation error details."}},"required":["error"],"description":"Validation error response payload."}}}},"401":{"description":"Unauthorized - invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}}}}},"/v1/analytics/query":{"post":{"summary":"Query analytics","description":"Query analytics metrics with optional grouping, sorting and filters.","parameters":[{"schema":{"type":"string","description":"Bearer token for a project API key. This endpoint returns data for that project only.","example":"Bearer vem_abcdefghijklmnopqrstuvwxyz123456"},"required":true,"name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dateRange":{"anyOf":[{"type":"string","enum":["live","1hr","24hrs","7days","30days","3months","6months","1year"]},{"type":"array","items":{"type":"string","description":"Either YYYY-MM-DD or UTC ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19|2026-01-19T12:30:00Z"},"minItems":2,"maxItems":2}],"description":"Can be either one of the preset strings below, or an array with two date strings [start, end]. Date strings can be either in YYYY-MM-DD format or UTC ISO-8601 format with second precision.","example":["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]},"metrics":{"type":"array","items":{"type":"string","enum":["users","pageviews","events","bounceRate","visitDuration"]},"default":["users","pageviews","events"],"description":"Metrics to calculate and include in the response."},"groupBy":{"type":"array","items":{"anyOf":[{"type":"string","enum":["country","city","page:origin","page:path","browser","deviceType","os","referrer","referrerType","utmCampaign","utmContent","utmMedium","utmSource","utmTerm","event:name"]},{"type":"string","enum":["interval:auto"]},{"type":"string","pattern":"^event:prop:([^\\r\\n]+)$","description":"Group by event property token","example":"event:prop:plan"}]},"default":[],"description":"Allowed values: \"interval:auto\", \"country\", \"city\", \"page:origin\", \"page:path\", \"browser\", \"deviceType\", \"os\", \"referrer\", \"referrerType\", \"utm*\", \"event:name\", or \"event:prop:<property_name>\". At the moment it's only possible to group by one field, please tell us if you need more.","example":["country"]},"orderBy":{"type":"array","items":{"type":"array","items":{"anyOf":[{"anyOf":[{"type":"string","enum":["users","pageviews","events","bounceRate","visitDuration"]},{"type":"string","enum":["country","city","page:origin","page:path","browser","deviceType","os","referrer","referrerType","utmCampaign","utmContent","utmMedium","utmSource","utmTerm","event:name"]},{"type":"string","enum":["date"]},{"type":"string","pattern":"^event:prop:([^\\r\\n]+)$","description":"Event property sort field token","example":"event:prop:plan"}]},{"type":"string","enum":["asc","desc"]}]},"minItems":2,"maxItems":2},"maxItems":1,"default":[],"description":"Gives you the ability to order by a specific field and direction. At the moment it's only possible to order by one field.","example":[["users","desc"]],"x-vemetric-docs":{"hideTupleVariantChildren":true}},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Limits the number of returned rows. Max value is 1000."},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of rows to skip from the start of the result set, to implement pagination."},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["page"]},"origin":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page origin (protocol + host). For example, \"https://example.com\"."},"path":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page path. For example, \"/blog\"."},"hash":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page hash. For example, \"#section1\"."}},"required":["type"],"description":"Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts.","example":{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}},{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Filter type identifier for event filters."},"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"required":["type"],"description":"Filter by event name and/or event property values.","example":{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}},{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"Filter type identifier for user filters."},"anonymous":{"type":"boolean","description":"Filter for anonymous (`true`) or identified (`false`) users.","example":true}},"required":["type","anonymous"],"description":"Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior).","example":{"type":"user","anonymous":true}},{"type":"object","properties":{"type":{"type":"string","enum":["location"],"description":"Filter type identifier for location filters."},"country":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more country codes (ISO-3166 alpha-2, e.g. \"US\")."},"city":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more city names.","example":{"value":["Berlin","New York"],"operator":"oneOf"}}},"required":["type"],"description":"Filter by geographic location fields.","example":{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}},{"type":"object","properties":{"type":{"type":"string","enum":["referrer"],"description":"Filter type identifier for referrer filters."},"value":{"type":"string","description":"Referrer value to match. Empty string represents direct/none referrer.","example":"Google"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["type","value","operator"],"description":"Filter by referrer name.","example":{"type":"referrer","operator":"eq","value":"Google"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerUrl"],"description":"Filter type identifier for referrer URL filters."},"value":{"type":"string","description":"Referrer URL value to match.","example":"https://google.com"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"contains"}},"required":["type","value","operator"],"description":"Filter by referrer URL.","example":{"type":"referrerUrl","operator":"contains","value":"google.com"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerType"],"description":"Filter type identifier for referrer type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of referrer types to match (for example: `search`, `social`, `email`, `direct`).","example":["search","social"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by referrer category/type.","example":{"type":"referrerType","operator":"oneOf","value":["search"]}},{"type":"object","properties":{"type":{"type":"string","enum":["utmTags"],"description":"Filter type identifier for UTM tag filters."},"utmCampaign":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM campaign."},"utmContent":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM content."},"utmMedium":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM medium."},"utmSource":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM source."},"utmTerm":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM term."}},"required":["type"],"description":"Filter by one or more UTM parameters.","example":{"type":"utmTags","utmSource":{"operator":"eq","value":"google"},"utmMedium":{"operator":"eq","value":"cpc"}}},{"type":"object","properties":{"type":{"type":"string","enum":["browser"],"description":"Filter type identifier for browser filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of browser names to match.","example":["Chrome","Safari"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by browser.","example":{"type":"browser","operator":"oneOf","value":["Chrome"]}},{"type":"object","properties":{"type":{"type":"string","enum":["device"],"description":"Filter type identifier for device type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of device types to match.","example":["desktop","mobile"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by device type.","example":{"type":"device","operator":"oneOf","value":["desktop"]}},{"type":"object","properties":{"type":{"type":"string","enum":["os"],"description":"Filter type identifier for operating system filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of operating system names to match.","example":["macOS","Windows"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by operating system.","example":{"type":"os","operator":"oneOf","value":["macOS"]}},{"type":"object","properties":{"type":{"type":"string","enum":["funnel"],"description":"Filter type identifier for funnel completion filters."},"id":{"type":"string","format":"uuid","description":"Funnel ID to evaluate for completion status.","example":"550e8400-e29b-41d4-a716-446655440000"},"step":{"type":"integer","minimum":0,"description":"Zero-based funnel step index to evaluate.","example":1},"operator":{"type":"string","enum":["completed","notCompleted"],"description":"Whether users must have completed or not completed the selected step.","example":"completed"}},"required":["type","id","step","operator"],"description":"Filter users based on funnel step completion.","example":{"type":"funnel","id":"550e8400-e29b-41d4-a716-446655440000","step":1,"operator":"completed"}}]},"description":"Ability to filter the results based on multiple criteria.","x-vemetric-docs":{"collapseByDefault":true}},"filtersOperator":{"anyOf":[{"type":"string","enum":["and"]},{"type":"string","enum":["or"]}],"default":"and","description":"Operator to apply between multiple filters. Can be either \"and\" or \"or\"."}},"required":["dateRange"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC start timestamp for the query window.","example":"2026-01-19T12:30:00Z"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC end timestamp for the query window.","example":"2026-01-19T12:30:00Z"}},"required":["from","to"],"description":"Resolved query period."},"query":{"type":"object","properties":{"dateRange":{"anyOf":[{"type":"string","enum":["live","1hr","24hrs","7days","30days","3months","6months","1year"]},{"type":"array","items":{"type":"string","description":"Either YYYY-MM-DD or UTC ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19|2026-01-19T12:30:00Z"},"minItems":2,"maxItems":2}],"description":"Echo of the incoming `dateRange` request field.","example":["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]},"groupBy":{"type":"array","items":{"anyOf":[{"type":"string","enum":["country","city","page:origin","page:path","browser","deviceType","os","referrer","referrerType","utmCampaign","utmContent","utmMedium","utmSource","utmTerm","event:name"]},{"type":"string","enum":["interval:auto"]},{"type":"string","pattern":"^event:prop:([^\\r\\n]+)$","description":"Group by event property token","example":"event:prop:plan"}]},"maxItems":1,"description":"Echo of the incoming `groupBy` request field."},"metrics":{"type":"array","items":{"type":"string","enum":["users","pageviews","events","bounceRate","visitDuration"]},"minItems":1,"description":"Resolved list of metrics used in the query."},"orderBy":{"type":"array","items":{"type":"array","items":{"anyOf":[{"anyOf":[{"type":"string","enum":["users","pageviews","events","bounceRate","visitDuration"]},{"type":"string","enum":["country","city","page:origin","page:path","browser","deviceType","os","referrer","referrerType","utmCampaign","utmContent","utmMedium","utmSource","utmTerm","event:name"]},{"type":"string","enum":["date"]},{"type":"string","pattern":"^event:prop:([^\\r\\n]+)$","description":"Event property sort field token","example":"event:prop:plan"}]},{"type":"string","enum":["asc","desc"]}]},"minItems":2,"maxItems":2},"maxItems":1,"description":"Echo of the incoming `orderBy` request field."},"limit":{"type":"integer","minimum":1,"description":"Echo of the incoming `limit` request field."},"offset":{"type":"integer","minimum":0,"description":"Echo of the incoming `offset` request field."},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["page"]},"origin":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page origin (protocol + host). For example, \"https://example.com\"."},"path":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page path. For example, \"/blog\"."},"hash":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page hash. For example, \"#section1\"."}},"required":["type"],"description":"Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts.","example":{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}},{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Filter type identifier for event filters."},"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"required":["type"],"description":"Filter by event name and/or event property values.","example":{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}},{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"Filter type identifier for user filters."},"anonymous":{"type":"boolean","description":"Filter for anonymous (`true`) or identified (`false`) users.","example":true}},"required":["type","anonymous"],"description":"Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior).","example":{"type":"user","anonymous":true}},{"type":"object","properties":{"type":{"type":"string","enum":["location"],"description":"Filter type identifier for location filters."},"country":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more country codes (ISO-3166 alpha-2, e.g. \"US\")."},"city":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more city names.","example":{"value":["Berlin","New York"],"operator":"oneOf"}}},"required":["type"],"description":"Filter by geographic location fields.","example":{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}},{"type":"object","properties":{"type":{"type":"string","enum":["referrer"],"description":"Filter type identifier for referrer filters."},"value":{"type":"string","description":"Referrer value to match. Empty string represents direct/none referrer.","example":"Google"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["type","value","operator"],"description":"Filter by referrer name.","example":{"type":"referrer","operator":"eq","value":"Google"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerUrl"],"description":"Filter type identifier for referrer URL filters."},"value":{"type":"string","description":"Referrer URL value to match.","example":"https://google.com"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"contains"}},"required":["type","value","operator"],"description":"Filter by referrer URL.","example":{"type":"referrerUrl","operator":"contains","value":"google.com"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerType"],"description":"Filter type identifier for referrer type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of referrer types to match (for example: `search`, `social`, `email`, `direct`).","example":["search","social"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by referrer category/type.","example":{"type":"referrerType","operator":"oneOf","value":["search"]}},{"type":"object","properties":{"type":{"type":"string","enum":["utmTags"],"description":"Filter type identifier for UTM tag filters."},"utmCampaign":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM campaign."},"utmContent":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM content."},"utmMedium":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM medium."},"utmSource":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM source."},"utmTerm":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM term."}},"required":["type"],"description":"Filter by one or more UTM parameters.","example":{"type":"utmTags","utmSource":{"operator":"eq","value":"google"},"utmMedium":{"operator":"eq","value":"cpc"}}},{"type":"object","properties":{"type":{"type":"string","enum":["browser"],"description":"Filter type identifier for browser filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of browser names to match.","example":["Chrome","Safari"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by browser.","example":{"type":"browser","operator":"oneOf","value":["Chrome"]}},{"type":"object","properties":{"type":{"type":"string","enum":["device"],"description":"Filter type identifier for device type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of device types to match.","example":["desktop","mobile"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by device type.","example":{"type":"device","operator":"oneOf","value":["desktop"]}},{"type":"object","properties":{"type":{"type":"string","enum":["os"],"description":"Filter type identifier for operating system filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of operating system names to match.","example":["macOS","Windows"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by operating system.","example":{"type":"os","operator":"oneOf","value":["macOS"]}},{"type":"object","properties":{"type":{"type":"string","enum":["funnel"],"description":"Filter type identifier for funnel completion filters."},"id":{"type":"string","format":"uuid","description":"Funnel ID to evaluate for completion status.","example":"550e8400-e29b-41d4-a716-446655440000"},"step":{"type":"integer","minimum":0,"description":"Zero-based funnel step index to evaluate.","example":1},"operator":{"type":"string","enum":["completed","notCompleted"],"description":"Whether users must have completed or not completed the selected step.","example":"completed"}},"required":["type","id","step","operator"],"description":"Filter users based on funnel step completion.","example":{"type":"funnel","id":"550e8400-e29b-41d4-a716-446655440000","step":1,"operator":"completed"}}]},"description":"Echo of the incoming `filters` request field."},"filtersOperator":{"anyOf":[{"type":"string","enum":["and"]},{"type":"string","enum":["or"]}],"description":"Echo of the incoming `filtersOperator` request field."}},"required":["dateRange","groupBy","metrics","orderBy","limit","offset"],"description":"Resolved query configuration used for this response."},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"description":"Applied row limit after internal normalization."},"offset":{"type":"integer","minimum":0,"description":"Applied row offset after internal normalization."},"returned":{"type":"integer","minimum":0,"description":"Number of rows returned in `data`. Can be used to determine if there are more rows available for pagination (when `returned` is equal to `limit`, there might be more rows available on the next page)."}},"required":["limit","offset","returned"],"description":"Pagination metadata for the response."},"data":{"type":"array","items":{"type":"object","properties":{"group":{"anyOf":[{"type":"object","properties":{},"additionalProperties":false},{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"UTC timestamp in ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19T12:30:00Z"}},"required":["date"],"description":"Grouping object for time interval queries.","example":{"date":"2026-01-18T00:00:00Z"}},{"type":"object","properties":{"country":{"type":"string"},"city":{"type":"string"},"page:origin":{"type":"string"},"page:path":{"type":"string"},"browser":{"type":"string"},"deviceType":{"type":"string"},"os":{"type":"string"},"referrer":{"type":"string"},"referrerType":{"type":"string"},"utmCampaign":{"type":"string"},"utmContent":{"type":"string"},"utmMedium":{"type":"string"},"utmSource":{"type":"string"},"utmTerm":{"type":"string"},"event:name":{"type":"string"}},"description":"Grouping object for predefined dimensions (e.g. country, city, browser, referrer).","example":{"country":"US"}},{"type":"object","additionalProperties":{"type":"string"},"description":"Grouping object for event property dimensions.","example":{"event:prop:plan":"pro"}}],"description":"Group values for this row. Empty object for aggregate queries."},"metrics":{"type":"object","properties":{"users":{"type":"number","description":"Unique users count for this row.","example":412},"pageviews":{"type":"number","description":"Pageview events count for this row.","example":1736},"events":{"type":"number","description":"Custom events count for this row.","example":43},"bounceRate":{"type":"number","nullable":true,"description":"Bounce rate percentage for this row. Can be `null` when not applicable for the selected grouping.","example":34.12},"visitDuration":{"type":"number","nullable":true,"description":"Average visit duration in seconds for this row. Can be `null` when not applicable for the selected grouping.","example":1222.45}},"description":"Calculated metric values for the row. Only requested metrics are returned."}},"required":["group","metrics"],"description":"One grouped analytics row."},"description":"Result rows for the query after grouping, sorting, and pagination."}},"required":["period","query","pagination","data"],"description":"Analytics query response.","example":{"period":{"from":"2026-01-18T00:00:00Z","to":"2026-01-19T23:59:59Z"},"query":{"dateRange":"30days","groupBy":["country"],"metrics":["users","events"],"orderBy":[["users","desc"]],"limit":100,"offset":0},"pagination":{"limit":100,"offset":0,"returned":2},"data":[{"group":{"country":"US"},"metrics":{"users":7,"events":43}}]}}}}},"400":{"description":"Bad request - invalid request payload or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Machine-readable validation error code."},"message":{"type":"string","description":"Human-readable validation summary."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Path to the invalid request field.","example":"groupBy.0"},"message":{"type":"string","description":"Validation error message for the field."}},"required":["field","message"]},"description":"Per-field validation issues."}},"required":["code","message","details"],"description":"Validation error details."}},"required":["error"],"description":"Validation error response payload."}}}},"401":{"description":"Unauthorized - invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"403":{"description":"Requested date range is not allowed for the current plan","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["PLAN_LIMIT_EXCEEDED"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}}}}},"/v1/filters/values":{"post":{"summary":"Get filter values","description":"Returns available filter values for one or more fields with pagination.","parameters":[{"schema":{"type":"string","description":"Bearer token for a project API key. This endpoint returns data for that project only.","example":"Bearer vem_abcdefghijklmnopqrstuvwxyz123456"},"required":true,"name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dateRange":{"anyOf":[{"type":"string","enum":["live","1hr","24hrs","7days","30days","3months","6months","1year"]},{"type":"array","items":{"type":"string","description":"Either YYYY-MM-DD or UTC ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19|2026-01-19T12:30:00Z"},"minItems":2,"maxItems":2}],"description":"Can be either one of the preset strings below, or an array with two date strings [start, end]. Date strings can be either in YYYY-MM-DD format or UTC ISO-8601 format with second precision.","example":["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]},"fields":{"type":"array","items":{"type":"string","enum":["country","city","page:origin","page:path","browser","deviceType","os","referrer","referrerType","utmCampaign","utmContent","utmMedium","utmSource","utmTerm","event:name"],"description":"Field token to retrieve filter values for.","example":"referrer"},"minItems":1,"maxItems":25,"description":"Field tokens to retrieve values for.","example":["referrer","country","event:name"]},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Limits the number of returned values per field."},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of values to skip per field from the start of the result set."}},"required":["dateRange","fields"],"description":"Request payload for retrieving available filter values per field."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC start timestamp for the query window.","example":"2026-01-19T12:30:00Z"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC end timestamp for the query window.","example":"2026-01-19T12:30:00Z"}},"required":["from","to"]},"query":{"type":"object","properties":{"dateRange":{"anyOf":[{"type":"string","enum":["live","1hr","24hrs","7days","30days","3months","6months","1year"]},{"type":"array","items":{"type":"string","description":"Either YYYY-MM-DD or UTC ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19|2026-01-19T12:30:00Z"},"minItems":2,"maxItems":2}],"description":"Echo of the incoming `dateRange` request field.","example":["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]},"fields":{"type":"array","items":{"type":"string","enum":["country","city","page:origin","page:path","browser","deviceType","os","referrer","referrerType","utmCampaign","utmContent","utmMedium","utmSource","utmTerm","event:name"],"description":"Field token to retrieve filter values for.","example":"referrer"},"minItems":1,"description":"Echo of the incoming `fields` request field."},"limit":{"type":"integer","minimum":1,"description":"Echo of the incoming `limit` request field."},"offset":{"type":"integer","minimum":0,"description":"Echo of the incoming `offset` request field."}},"required":["dateRange","fields","limit","offset"]},"data":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["country","city","page:origin","page:path","browser","deviceType","os","referrer","referrerType","utmCampaign","utmContent","utmMedium","utmSource","utmTerm","event:name"],"description":"Field token this value list belongs to.","example":"referrer"},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"description":"Applied page size for this field."},"offset":{"type":"integer","minimum":0,"description":"Applied page offset for this field."},"returned":{"type":"integer","minimum":0,"description":"Number of values returned for this field."}},"required":["limit","offset","returned"]},"values":{"type":"array","items":{"type":"string"},"description":"Paginated values for this field.","example":["Google","Newsletter","Bing"]}},"required":["field","pagination","values"]},"description":"One value list per requested field."}},"required":["period","query","data"],"description":"Filter values query response."}}}},"400":{"description":"Bad request - invalid request payload or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Machine-readable validation error code."},"message":{"type":"string","description":"Human-readable validation summary."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Path to the invalid request field.","example":"groupBy.0"},"message":{"type":"string","description":"Validation error message for the field."}},"required":["field","message"]},"description":"Per-field validation issues."}},"required":["code","message","details"],"description":"Validation error details."}},"required":["error"],"description":"Validation error response payload."}}}},"401":{"description":"Unauthorized - invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"403":{"description":"Requested date range is not allowed for the current plan","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["PLAN_LIMIT_EXCEEDED"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}}}}},"/v1/users":{"post":{"summary":"List users","description":"Returns a list of users with optional filters, sorting and date range.","parameters":[{"schema":{"type":"string","description":"Bearer token for a project API key. This endpoint returns data for that project only.","example":"Bearer vem_abcdefghijklmnopqrstuvwxyz123456"},"required":true,"name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dateRange":{"anyOf":[{"type":"string","enum":["live","1hr","24hrs","7days","30days","3months","6months","1year"]},{"type":"array","items":{"type":"string","description":"Either YYYY-MM-DD or UTC ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19|2026-01-19T12:30:00Z"},"minItems":2,"maxItems":2}],"description":"Can be either one of the preset strings below, or an array with two date strings [start, end]. Date strings can be either in YYYY-MM-DD format or UTC ISO-8601 format with second precision.","example":["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["page"]},"origin":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page origin (protocol + host). For example, \"https://example.com\"."},"path":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page path. For example, \"/blog\"."},"hash":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page hash. For example, \"#section1\"."}},"required":["type"],"description":"Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts.","example":{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}},{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Filter type identifier for event filters."},"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"required":["type"],"description":"Filter by event name and/or event property values.","example":{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}},{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"Filter type identifier for user filters."},"anonymous":{"type":"boolean","description":"Filter for anonymous (`true`) or identified (`false`) users.","example":true}},"required":["type","anonymous"],"description":"Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior).","example":{"type":"user","anonymous":true}},{"type":"object","properties":{"type":{"type":"string","enum":["location"],"description":"Filter type identifier for location filters."},"country":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more country codes (ISO-3166 alpha-2, e.g. \"US\")."},"city":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more city names.","example":{"value":["Berlin","New York"],"operator":"oneOf"}}},"required":["type"],"description":"Filter by geographic location fields.","example":{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}},{"type":"object","properties":{"type":{"type":"string","enum":["referrer"],"description":"Filter type identifier for referrer filters."},"value":{"type":"string","description":"Referrer value to match. Empty string represents direct/none referrer.","example":"Google"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["type","value","operator"],"description":"Filter by referrer name.","example":{"type":"referrer","operator":"eq","value":"Google"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerUrl"],"description":"Filter type identifier for referrer URL filters."},"value":{"type":"string","description":"Referrer URL value to match.","example":"https://google.com"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"contains"}},"required":["type","value","operator"],"description":"Filter by referrer URL.","example":{"type":"referrerUrl","operator":"contains","value":"google.com"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerType"],"description":"Filter type identifier for referrer type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of referrer types to match (for example: `search`, `social`, `email`, `direct`).","example":["search","social"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by referrer category/type.","example":{"type":"referrerType","operator":"oneOf","value":["search"]}},{"type":"object","properties":{"type":{"type":"string","enum":["utmTags"],"description":"Filter type identifier for UTM tag filters."},"utmCampaign":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM campaign."},"utmContent":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM content."},"utmMedium":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM medium."},"utmSource":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM source."},"utmTerm":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM term."}},"required":["type"],"description":"Filter by one or more UTM parameters.","example":{"type":"utmTags","utmSource":{"operator":"eq","value":"google"},"utmMedium":{"operator":"eq","value":"cpc"}}},{"type":"object","properties":{"type":{"type":"string","enum":["browser"],"description":"Filter type identifier for browser filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of browser names to match.","example":["Chrome","Safari"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by browser.","example":{"type":"browser","operator":"oneOf","value":["Chrome"]}},{"type":"object","properties":{"type":{"type":"string","enum":["device"],"description":"Filter type identifier for device type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of device types to match.","example":["desktop","mobile"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by device type.","example":{"type":"device","operator":"oneOf","value":["desktop"]}},{"type":"object","properties":{"type":{"type":"string","enum":["os"],"description":"Filter type identifier for operating system filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of operating system names to match.","example":["macOS","Windows"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by operating system.","example":{"type":"os","operator":"oneOf","value":["macOS"]}},{"type":"object","properties":{"type":{"type":"string","enum":["funnel"],"description":"Filter type identifier for funnel completion filters."},"id":{"type":"string","format":"uuid","description":"Funnel ID to evaluate for completion status.","example":"550e8400-e29b-41d4-a716-446655440000"},"step":{"type":"integer","minimum":0,"description":"Zero-based funnel step index to evaluate.","example":1},"operator":{"type":"string","enum":["completed","notCompleted"],"description":"Whether users must have completed or not completed the selected step.","example":"completed"}},"required":["type","id","step","operator"],"description":"Filter users based on funnel step completion.","example":{"type":"funnel","id":"550e8400-e29b-41d4-a716-446655440000","step":1,"operator":"completed"}}]},"description":"Optional filters to restrict the user list.","x-vemetric-docs":{"collapseByDefault":true}},"filtersOperator":{"anyOf":[{"type":"string","enum":["and"]},{"type":"string","enum":["or"]}],"default":"and","description":"Operator to apply between multiple filters."},"orderBy":{"type":"array","items":{"anyOf":[{"type":"array","items":{"anyOf":[{"type":"string","enum":["lastSeenAt","displayName","identifier","country"],"description":"Sortable user field.","example":"lastSeenAt"},{"type":"string","enum":["asc","desc"]}]},"minItems":2,"maxItems":2},{"type":"array","items":{"anyOf":[{"type":"string","enum":["lastEventFired"],"description":"Special sort field that sorts users by when they last fired a matching event filter.","example":"lastEventFired"},{"type":"string","enum":["asc","desc"]},{"type":"object","properties":{"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"description":"Event filter used to determine when a user last fired a matching event."}]},"minItems":3,"maxItems":3}]},"maxItems":1,"default":[["lastSeenAt","desc"]],"description":"Gives you the ability to order users by a specific field and direction. At the moment it's only possible to order by one field.","x-vemetric-docs":{"hideTupleVariantChildren":true},"example":[["lastEventFired","desc",{"name":{"operator":"eq","value":"Signup"},"properties":[{"property":"provider","operator":"eq","value":"google"}]}]]},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Limits the number of returned users. Max value is 1000."},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of users to skip from the start of the result set."}},"required":["dateRange"],"description":"Request payload for querying a paginated list of users."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC start timestamp for the user list query window.","example":"2026-01-19T12:30:00Z"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC end timestamp for the user list query window.","example":"2026-01-19T12:30:00Z"}},"required":["from","to"],"description":"Resolved query period."},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"description":"Applied row limit."},"offset":{"type":"integer","minimum":0,"description":"Applied row offset."},"returned":{"type":"integer","minimum":0,"description":"Number of user rows returned in `users`."}},"required":["limit","offset","returned"],"description":"Pagination metadata."},"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Vemetric's internal user ID.","example":"123"},"identifier":{"type":"string","nullable":true,"description":"User identifier if available (the value you provided to identify the user).","example":"john@example.com"},"displayName":{"type":"string","nullable":true,"description":"User display name if available.","example":"John Doe"},"country":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code, or `null` when unknown.","example":"US"},"city":{"type":"string","nullable":true,"description":"User city, or `null` when unknown.","example":"Berlin"},"lastSeenAt":{"type":"string","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"UTC timestamp of the latest activity for this user within the selected period.","example":"2026-01-19T12:30:00Z"},"lastEventFiredAt":{"type":"string","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"UTC timestamp of when the user last fired the event referenced by `orderBy[0][2]`. Populated only for `orderBy[0][0] = \"lastEventFired\"`, otherwise `null`.","example":"2026-01-19T12:30:00Z"},"avatarUrl":{"type":"string","nullable":true,"description":"Avatar URL if available.","example":"https://cdn.example.com/avatar.png"},"data":{"type":"object","additionalProperties":{"nullable":true},"description":"Data attributes collected for this user.","example":{"plan":"pro","company":"Vemetric"}},"anonymous":{"type":"boolean","description":"Whether the user is anonymous (not identified).","example":false}},"required":["id","identifier","displayName","country","city","lastSeenAt","lastEventFiredAt","avatarUrl","data","anonymous"],"description":"Compact summary user row."},"description":"List of user rows for the current page."}},"required":["period","pagination","users"],"description":"Successful users list response payload."}}}},"400":{"description":"Bad request - invalid request payload or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Machine-readable validation error code."},"message":{"type":"string","description":"Human-readable validation summary."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Path to the invalid request field.","example":"groupBy.0"},"message":{"type":"string","description":"Validation error message for the field."}},"required":["field","message"]},"description":"Per-field validation issues."}},"required":["code","message","details"],"description":"Validation error details."}},"required":["error"],"description":"Validation error response payload."}}}},"401":{"description":"Unauthorized - invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"403":{"description":"Requested date range is not allowed for the current plan","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["PLAN_LIMIT_EXCEEDED"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}}}}},"/v1/users/single":{"get":{"summary":"Get user","description":"Returns one user by id or identifier.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Vemetric's internal user ID. You have to either provide `id` or `identifier`.","example":"123"},"required":false,"name":"id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"User identifier value. You have to either provide `identifier` or `id`.","example":"your-user-id"},"required":false,"name":"identifier","in":"query"},{"schema":{"type":"string","description":"Bearer token for a project API key. This endpoint returns data for that project only.","example":"Bearer vem_abcdefghijklmnopqrstuvwxyz123456"},"required":true,"name":"authorization","in":"header"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"Vemetric's internal user ID.","example":"123"},"identifier":{"type":"string","nullable":true,"description":"User identifier if available (the value you provided to identify the user).","example":"john@example.com"},"displayName":{"type":"string","nullable":true,"description":"User display name if available.","example":"John Doe"},"country":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code, or `null` when unknown.","example":"US"},"city":{"type":"string","nullable":true,"description":"User city, or `null` when unknown.","example":"Berlin"},"lastSeenAt":{"type":"string","nullable":true,"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"UTC timestamp of the latest activity for this user within the selected period.","example":"2026-01-19T12:30:00Z"},"avatarUrl":{"type":"string","nullable":true,"description":"Avatar URL if available.","example":"https://cdn.example.com/avatar.png"},"data":{"type":"object","additionalProperties":{"nullable":true},"description":"Data attributes collected for this user.","example":{"plan":"pro","company":"Vemetric"}},"anonymous":{"type":"boolean","description":"Whether the user is anonymous (not identified).","example":false}},"required":["id","identifier","displayName","country","city","lastSeenAt","avatarUrl","data","anonymous"],"description":"Resolved user row."}},"required":["user"],"description":"Successful single user response payload."}}}},"400":{"description":"Bad request - invalid request payload or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Machine-readable validation error code."},"message":{"type":"string","description":"Human-readable validation summary."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Path to the invalid request field.","example":"groupBy.0"},"message":{"type":"string","description":"Validation error message for the field."}},"required":["field","message"]},"description":"Per-field validation issues."}},"required":["code","message","details"],"description":"Validation error details."}},"required":["error"],"description":"Validation error response payload."}}}},"401":{"description":"Unauthorized - invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"404":{"description":"User was not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["USER_NOT_FOUND"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}}}}},"/v1/users/events":{"post":{"summary":"List user events","description":"Returns events for one user within a specified date range and with optional filters.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Vemetric's internal user ID. You have to either provide `id` or `identifier`.","example":"123"},"required":false,"name":"id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"User identifier value. You have to either provide `identifier` or `id`.","example":"your-user-id"},"required":false,"name":"identifier","in":"query"},{"schema":{"type":"string","description":"Bearer token for a project API key. This endpoint returns data for that project only.","example":"Bearer vem_abcdefghijklmnopqrstuvwxyz123456"},"required":true,"name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dateRange":{"anyOf":[{"type":"string","enum":["live","1hr","24hrs","7days","30days","3months","6months","1year"]},{"type":"array","items":{"type":"string","description":"Either YYYY-MM-DD or UTC ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19|2026-01-19T12:30:00Z"},"minItems":2,"maxItems":2}],"description":"Can be either one of the preset strings below, or an array with two date strings [start, end]. Date strings can be either in YYYY-MM-DD format or UTC ISO-8601 format with second precision.","example":["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Filter type identifier for event filters."},"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"required":["type"],"description":"Filter by event name and/or event property values.","example":{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}},{"type":"object","properties":{"type":{"type":"string","enum":["page"]},"origin":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page origin (protocol + host). For example, \"https://example.com\"."},"path":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page path. For example, \"/blog\"."},"hash":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page hash. For example, \"#section1\"."}},"required":["type"],"description":"Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts.","example":{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}},{"type":"object","properties":{"type":{"type":"string","enum":["browser"],"description":"Filter type identifier for browser filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of browser names to match.","example":["Chrome","Safari"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by browser.","example":{"type":"browser","operator":"oneOf","value":["Chrome"]}},{"type":"object","properties":{"type":{"type":"string","enum":["device"],"description":"Filter type identifier for device type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of device types to match.","example":["desktop","mobile"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by device type.","example":{"type":"device","operator":"oneOf","value":["desktop"]}},{"type":"object","properties":{"type":{"type":"string","enum":["os"],"description":"Filter type identifier for operating system filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of operating system names to match.","example":["macOS","Windows"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by operating system.","example":{"type":"os","operator":"oneOf","value":["macOS"]}}]},"description":"Optional filters to restrict returned events.","x-vemetric-docs":{"collapseByDefault":true}},"filtersOperator":{"anyOf":[{"type":"string","enum":["and"]},{"type":"string","enum":["or"]}],"default":"and","description":"Operator to apply between multiple filters."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Limits the number of returned events. Max value is 1000."},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of events to skip from the start of the result set."}},"required":["dateRange"],"description":"Request payload for querying one user’s events."}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC start timestamp for the events query window.","example":"2026-01-19T12:30:00Z"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC end timestamp for the events query window.","example":"2026-01-19T12:30:00Z"}},"required":["from","to"],"description":"Resolved query period."},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"description":"Applied row limit."},"offset":{"type":"integer","minimum":0,"description":"Applied row offset."},"returned":{"type":"integer","minimum":0,"description":"Number of event rows returned in `events`."}},"required":["limit","offset","returned"],"description":"Pagination metadata."},"events":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session id of the event."},"name":{"type":"string","description":"Event name."},"isPageView":{"type":"boolean","description":"Whether this event is a pageview."},"createdAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"UTC timestamp when the event was created.","example":"2026-01-19T12:30:00Z"},"origin":{"type":"string","nullable":true,"description":"URL origin if available (for pageviews)."},"path":{"type":"string","nullable":true,"description":"URL path if available (for pageviews)."},"hash":{"type":"string","nullable":true,"description":"URL hash if available (for pageviews)."},"data":{"type":"object","additionalProperties":{"nullable":true},"description":"Event data key-value map.","example":{"plan":"pro"}}},"required":["sessionId","name","isPageView","createdAt","origin","path","hash","data"],"description":"One event row."},"description":"List of user events for the requested page."}},"required":["period","pagination","events"],"description":"Successful user events response payload."}}}},"400":{"description":"Bad request - invalid request payload or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Machine-readable validation error code."},"message":{"type":"string","description":"Human-readable validation summary."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Path to the invalid request field.","example":"groupBy.0"},"message":{"type":"string","description":"Validation error message for the field."}},"required":["field","message"]},"description":"Per-field validation issues."}},"required":["code","message","details"],"description":"Validation error details."}},"required":["error"],"description":"Validation error response payload."}}}},"401":{"description":"Unauthorized - invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"403":{"description":"Requested date range is not allowed for the current plan","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["PLAN_LIMIT_EXCEEDED"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"User was not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["USER_NOT_FOUND"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}}}}},"/v1/funnels":{"get":{"summary":"List funnels","description":"Returns the list of funnels for the authenticated project.","parameters":[{"schema":{"type":"string","description":"Bearer token for a project API key. This endpoint returns data for that project only.","example":"Bearer vem_abcdefghijklmnopqrstuvwxyz123456"},"required":true,"name":"authorization","in":"header"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"funnels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique funnel id.","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"Funnel name.","example":"Signup Funnel"},"icon":{"type":"string","nullable":true,"description":"Optional funnel icon.","example":"🚀"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":3,"description":"Unique funnel step id.","example":"zvpslSIPFJQ6oiRCXPMm3"},"name":{"type":"string","description":"Name of the funnel step.","example":"Visited Landing Page"},"filter":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["page"]},"origin":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page origin (protocol + host). For example, \"https://example.com\"."},"path":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page path. For example, \"/blog\"."},"hash":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page hash. For example, \"#section1\"."}},"required":["type"],"description":"Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts.","example":{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}},{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Filter type identifier for event filters."},"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"required":["type"],"description":"Filter by event name and/or event property values.","example":{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}}],"description":"Condition that determines when the funnel step is considered completed. Either a pageview or a custom event filter."}},"required":["id","name","filter"]},"description":"Ordered funnel steps."},"createdAt":{"type":"string","format":"date-time","description":"Funnel creation timestamp (ISO 8601).","example":"2026-03-01T10:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","description":"Funnel last update timestamp (ISO 8601).","example":"2026-03-02T11:30:00.000Z"}},"required":["id","name","icon","steps","createdAt","updatedAt"]},"description":"All available funnels for the authenticated project."}},"required":["funnels"]}}}},"400":{"description":"Bad request - invalid request payload or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Machine-readable validation error code."},"message":{"type":"string","description":"Human-readable validation summary."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Path to the invalid request field.","example":"groupBy.0"},"message":{"type":"string","description":"Validation error message for the field."}},"required":["field","message"]},"description":"Per-field validation issues."}},"required":["code","message","details"],"description":"Validation error details."}},"required":["error"],"description":"Validation error response payload."}}}},"401":{"description":"Unauthorized - invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}}}}},"/v1/funnels/{id}":{"post":{"summary":"Get funnel results","description":"Returns results for a funnel in the given date range and with optional filters.","parameters":[{"schema":{"type":"string","description":"Unique funnel id.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Bearer token for a project API key. This endpoint returns data for that project only.","example":"Bearer vem_abcdefghijklmnopqrstuvwxyz123456"},"required":true,"name":"authorization","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dateRange":{"anyOf":[{"type":"string","enum":["live","1hr","24hrs","7days","30days","3months","6months","1year"]},{"type":"array","items":{"type":"string","description":"Either YYYY-MM-DD or UTC ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19|2026-01-19T12:30:00Z"},"minItems":2,"maxItems":2}],"description":"Can be either one of the preset strings below, or an array with two date strings [start, end]. Date strings can be either in YYYY-MM-DD format or UTC ISO-8601 format with second precision.","example":["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["page"]},"origin":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page origin (protocol + host). For example, \"https://example.com\"."},"path":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page path. For example, \"/blog\"."},"hash":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page hash. For example, \"#section1\"."}},"required":["type"],"description":"Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts.","example":{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}},{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Filter type identifier for event filters."},"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"required":["type"],"description":"Filter by event name and/or event property values.","example":{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}},{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"Filter type identifier for user filters."},"anonymous":{"type":"boolean","description":"Filter for anonymous (`true`) or identified (`false`) users.","example":true}},"required":["type","anonymous"],"description":"Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior).","example":{"type":"user","anonymous":true}},{"type":"object","properties":{"type":{"type":"string","enum":["location"],"description":"Filter type identifier for location filters."},"country":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more country codes (ISO-3166 alpha-2, e.g. \"US\")."},"city":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more city names.","example":{"value":["Berlin","New York"],"operator":"oneOf"}}},"required":["type"],"description":"Filter by geographic location fields.","example":{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}},{"type":"object","properties":{"type":{"type":"string","enum":["referrer"],"description":"Filter type identifier for referrer filters."},"value":{"type":"string","description":"Referrer value to match. Empty string represents direct/none referrer.","example":"Google"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["type","value","operator"],"description":"Filter by referrer name.","example":{"type":"referrer","operator":"eq","value":"Google"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerUrl"],"description":"Filter type identifier for referrer URL filters."},"value":{"type":"string","description":"Referrer URL value to match.","example":"https://google.com"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"contains"}},"required":["type","value","operator"],"description":"Filter by referrer URL.","example":{"type":"referrerUrl","operator":"contains","value":"google.com"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerType"],"description":"Filter type identifier for referrer type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of referrer types to match (for example: `search`, `social`, `email`, `direct`).","example":["search","social"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by referrer category/type.","example":{"type":"referrerType","operator":"oneOf","value":["search"]}},{"type":"object","properties":{"type":{"type":"string","enum":["utmTags"],"description":"Filter type identifier for UTM tag filters."},"utmCampaign":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM campaign."},"utmContent":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM content."},"utmMedium":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM medium."},"utmSource":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM source."},"utmTerm":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM term."}},"required":["type"],"description":"Filter by one or more UTM parameters.","example":{"type":"utmTags","utmSource":{"operator":"eq","value":"google"},"utmMedium":{"operator":"eq","value":"cpc"}}},{"type":"object","properties":{"type":{"type":"string","enum":["browser"],"description":"Filter type identifier for browser filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of browser names to match.","example":["Chrome","Safari"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by browser.","example":{"type":"browser","operator":"oneOf","value":["Chrome"]}},{"type":"object","properties":{"type":{"type":"string","enum":["device"],"description":"Filter type identifier for device type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of device types to match.","example":["desktop","mobile"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by device type.","example":{"type":"device","operator":"oneOf","value":["desktop"]}},{"type":"object","properties":{"type":{"type":"string","enum":["os"],"description":"Filter type identifier for operating system filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of operating system names to match.","example":["macOS","Windows"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by operating system.","example":{"type":"os","operator":"oneOf","value":["macOS"]}},{"type":"object","properties":{"type":{"type":"string","enum":["funnel"],"description":"Filter type identifier for funnel completion filters."},"id":{"type":"string","format":"uuid","description":"Funnel ID to evaluate for completion status.","example":"550e8400-e29b-41d4-a716-446655440000"},"step":{"type":"integer","minimum":0,"description":"Zero-based funnel step index to evaluate.","example":1},"operator":{"type":"string","enum":["completed","notCompleted"],"description":"Whether users must have completed or not completed the selected step.","example":"completed"}},"required":["type","id","step","operator"],"description":"Filter users based on funnel step completion.","example":{"type":"funnel","id":"550e8400-e29b-41d4-a716-446655440000","step":1,"operator":"completed"}}]},"description":"Optional filters applied before funnel step evaluation.","x-vemetric-docs":{"collapseByDefault":true}},"filtersOperator":{"anyOf":[{"type":"string","enum":["and"]},{"type":"string","enum":["or"]}],"default":"and","description":"Operator to apply between multiple filters."}},"required":["dateRange"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"object","properties":{"from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC start timestamp for the query window.","example":"2026-01-19T12:30:00Z"},"to":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$","description":"Resolved UTC end timestamp for the query window.","example":"2026-01-19T12:30:00Z"}},"required":["from","to"],"description":"Resolved query period."},"query":{"type":"object","properties":{"dateRange":{"anyOf":[{"type":"string","enum":["live","1hr","24hrs","7days","30days","3months","6months","1year"]},{"type":"array","items":{"type":"string","description":"Either YYYY-MM-DD or UTC ISO-8601 format with second precision (no milliseconds).","example":"2026-01-19|2026-01-19T12:30:00Z"},"minItems":2,"maxItems":2}],"description":"Echo of the incoming `dateRange` request field.","example":["2026-01-01T12:00:00Z","2026-01-31T12:00:00Z"]},"filters":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["page"]},"origin":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page origin (protocol + host). For example, \"https://example.com\"."},"path":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page path. For example, \"/blog\"."},"hash":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page hash. For example, \"#section1\"."}},"required":["type"],"description":"Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts.","example":{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}},{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Filter type identifier for event filters."},"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"required":["type"],"description":"Filter by event name and/or event property values.","example":{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}},{"type":"object","properties":{"type":{"type":"string","enum":["user"],"description":"Filter type identifier for user filters."},"anonymous":{"type":"boolean","description":"Filter for anonymous (`true`) or identified (`false`) users.","example":true}},"required":["type","anonymous"],"description":"Ability to filter for either anonymous or identified users. This is useful when you want to include only known users (for example, for a retention analysis) or only anonymous users (for example, to analyze new visitor behavior).","example":{"type":"user","anonymous":true}},{"type":"object","properties":{"type":{"type":"string","enum":["location"],"description":"Filter type identifier for location filters."},"country":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more country codes (ISO-3166 alpha-2, e.g. \"US\")."},"city":{"type":"object","properties":{"value":{"type":"array","items":{"type":"string"},"description":"List of values to filter by"},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"Operator to apply for the list filter. The \"any\" operator means that any value is accepted and effectively disables the filter."}},"required":["value","operator"],"description":"Filter by one or more city names.","example":{"value":["Berlin","New York"],"operator":"oneOf"}}},"required":["type"],"description":"Filter by geographic location fields.","example":{"type":"location","country":{"operator":"oneOf","value":["US","DE"]},"city":{"operator":"oneOf","value":["Berlin"]}}},{"type":"object","properties":{"type":{"type":"string","enum":["referrer"],"description":"Filter type identifier for referrer filters."},"value":{"type":"string","description":"Referrer value to match. Empty string represents direct/none referrer.","example":"Google"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["type","value","operator"],"description":"Filter by referrer name.","example":{"type":"referrer","operator":"eq","value":"Google"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerUrl"],"description":"Filter type identifier for referrer URL filters."},"value":{"type":"string","description":"Referrer URL value to match.","example":"https://google.com"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"contains"}},"required":["type","value","operator"],"description":"Filter by referrer URL.","example":{"type":"referrerUrl","operator":"contains","value":"google.com"}},{"type":"object","properties":{"type":{"type":"string","enum":["referrerType"],"description":"Filter type identifier for referrer type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of referrer types to match (for example: `search`, `social`, `email`, `direct`).","example":["search","social"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by referrer category/type.","example":{"type":"referrerType","operator":"oneOf","value":["search"]}},{"type":"object","properties":{"type":{"type":"string","enum":["utmTags"],"description":"Filter type identifier for UTM tag filters."},"utmCampaign":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM campaign."},"utmContent":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM content."},"utmMedium":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM medium."},"utmSource":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM source."},"utmTerm":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by UTM term."}},"required":["type"],"description":"Filter by one or more UTM parameters.","example":{"type":"utmTags","utmSource":{"operator":"eq","value":"google"},"utmMedium":{"operator":"eq","value":"cpc"}}},{"type":"object","properties":{"type":{"type":"string","enum":["browser"],"description":"Filter type identifier for browser filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of browser names to match.","example":["Chrome","Safari"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by browser.","example":{"type":"browser","operator":"oneOf","value":["Chrome"]}},{"type":"object","properties":{"type":{"type":"string","enum":["device"],"description":"Filter type identifier for device type filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of device types to match.","example":["desktop","mobile"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by device type.","example":{"type":"device","operator":"oneOf","value":["desktop"]}},{"type":"object","properties":{"type":{"type":"string","enum":["os"],"description":"Filter type identifier for operating system filters."},"value":{"type":"array","items":{"type":"string"},"description":"List of operating system names to match.","example":["macOS","Windows"]},"operator":{"anyOf":[{"type":"string","enum":["any"]},{"type":"string","enum":["oneOf"]},{"type":"string","enum":["noneOf"]}],"description":"List matching operator for `value`.","example":"oneOf"}},"required":["type","value","operator"],"description":"Filter by operating system.","example":{"type":"os","operator":"oneOf","value":["macOS"]}},{"type":"object","properties":{"type":{"type":"string","enum":["funnel"],"description":"Filter type identifier for funnel completion filters."},"id":{"type":"string","format":"uuid","description":"Funnel ID to evaluate for completion status.","example":"550e8400-e29b-41d4-a716-446655440000"},"step":{"type":"integer","minimum":0,"description":"Zero-based funnel step index to evaluate.","example":1},"operator":{"type":"string","enum":["completed","notCompleted"],"description":"Whether users must have completed or not completed the selected step.","example":"completed"}},"required":["type","id","step","operator"],"description":"Filter users based on funnel step completion.","example":{"type":"funnel","id":"550e8400-e29b-41d4-a716-446655440000","step":1,"operator":"completed"}}]},"description":"Echo of the incoming `filters` request field."},"filtersOperator":{"anyOf":[{"type":"string","enum":["and"]},{"type":"string","enum":["or"]}],"description":"Echo of the incoming `filtersOperator` request field."}},"required":["dateRange"],"description":"Resolved query configuration used for this response."},"funnel":{"type":"object","properties":{"id":{"type":"string","description":"Unique funnel id.","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"Funnel name.","example":"Signup Funnel"},"icon":{"type":"string","nullable":true,"description":"Optional funnel icon.","example":"🚀"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":3,"description":"Unique funnel step id.","example":"zvpslSIPFJQ6oiRCXPMm3"},"name":{"type":"string","description":"Name of the funnel step.","example":"Visited Landing Page"},"filter":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["page"]},"origin":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page origin (protocol + host). For example, \"https://example.com\"."},"path":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page path. For example, \"/blog\"."},"hash":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter based on the page hash. For example, \"#section1\"."}},"required":["type"],"description":"Filter based on specific page view properties, like the full URL (origin + path + hash) or its individual parts.","example":{"type":"page","origin":{"value":"https://example.com","operator":"eq"},"path":{"value":"/blog","operator":"startsWith"}}},{"type":"object","properties":{"type":{"type":"string","enum":["event"],"description":"Filter type identifier for event filters."},"name":{"type":"object","properties":{"value":{"type":"string","description":"Value to filter by"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"Operator to apply for the string filter. \"eq\" means equals, \"notEq\" means not equals."}},"required":["value","operator"],"description":"Filter by event name."},"properties":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string","description":"Event property key inside custom event data.","example":"provider"},"value":{"type":"string","description":"Event property value to compare against.","example":"github"},"operator":{"type":"string","enum":["any","eq","notEq","contains","notContains","startsWith","endsWith"],"description":"String matching operator for `value`.","example":"eq"}},"required":["property","value","operator"]},"description":"Filter by one or more custom event properties."}},"required":["type"],"description":"Filter by event name and/or event property values.","example":{"type":"event","name":{"operator":"eq","value":"signup"},"properties":[{"property":"plan","operator":"eq","value":"pro"}]}}],"description":"Condition that determines when the funnel step is considered completed. Either a pageview or a custom event filter."}},"required":["id","name","filter"]},"description":"Ordered funnel steps."},"createdAt":{"type":"string","format":"date-time","description":"Funnel creation timestamp (ISO 8601).","example":"2026-03-01T10:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","description":"Funnel last update timestamp (ISO 8601).","example":"2026-03-02T11:30:00.000Z"}},"required":["id","name","icon","steps","createdAt","updatedAt"],"description":"Funnel definition for which these results were computed."},"results":{"type":"object","properties":{"activeUsers":{"type":"integer","minimum":0,"description":"Users active in the period and matching filters.","example":245},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":3,"description":"Unique funnel step id.","example":"zvpslSIPFJQ6oiRCXPMm3"},"name":{"type":"string","description":"Name of the funnel step.","example":"Visited Landing Page"},"users":{"type":"integer","minimum":0,"description":"Users that reached this step.","example":128},"conversionRate":{"type":"number","minimum":0,"maximum":100,"description":"Step-to-step conversion rate in percent. First step is always 100 (or 0 if empty).","example":65.3}},"required":["id","name","users","conversionRate"]},"description":"Per-step user counts in funnel order."},"conversionRate":{"type":"number","minimum":0,"maximum":100,"description":"Conversion rate from first funnel step to last funnel step, in percent.","example":32.81},"activeUserConversionRate":{"type":"number","minimum":0,"maximum":100,"description":"Conversion rate from active users to last funnel step, in percent.","example":18.26}},"required":["activeUsers","steps","conversionRate","activeUserConversionRate"],"description":"Funnel results for the given query."}},"required":["period","query","funnel","results"]}}}},"400":{"description":"Bad request - invalid request payload or parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["VALIDATION_ERROR"],"description":"Machine-readable validation error code."},"message":{"type":"string","description":"Human-readable validation summary."},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Path to the invalid request field.","example":"groupBy.0"},"message":{"type":"string","description":"Validation error message for the field."}},"required":["field","message"]},"description":"Per-field validation issues."}},"required":["code","message","details"],"description":"Validation error details."}},"required":["error"],"description":"Validation error response payload."}}}},"401":{"description":"Unauthorized - invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"403":{"description":"Requested date range is not allowed for the current plan","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["PLAN_LIMIT_EXCEEDED"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Funnel was not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["FUNNEL_NOT_FOUND"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}},"500":{"description":"Unexpected internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"required":["code","message"],"description":"Error details."}},"required":["error"],"description":"Error response payload."}}}}}}}}}