Analytics API reference
Project-owned event collection and analytics reporting. Write-key analytics event ingestion.
Published contracts: @socra/analytics-api@0.0.1, @socra/analytics-api@0.0.1.
Base URL
https://analytics.socra.cloudDatasets
An isolated collection of analytics events sharing retention and reporting settings.
Create dataset
POST
/v1/projects/{project_id}/datasetsPath parameters
project_idcustomrequiredRequest body
namestringrequiredmin length: 1 · max length: 256environmentstringoptionaldefault: "production" · min length: 1 · max length: 64 · pattern: ^[a-z0-9][a-z0-9._-]*$retention_daysintegeroptionaldefault: 90 · min: 1 · max: 3650Response
9 fields
idcustomrequiredproject_idcustomrequirednamestringrequiredenvironmentstringrequiredmin length: 1 · max length: 64 · pattern: ^[a-z0-9][a-z0-9._-]*$retention_daysintegerrequiredgreater than: 0 · max: 9007199254740991status"active" | "suspended"requiredwrite_keystringrequiredcreated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$updated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$List datasets
GET
/v1/projects/{project_id}/datasetsPath parameters
project_idcustomrequiredQuery parameters
limitintegeroptionalmin: 1 · max: 100afterstringoptionalResponse
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredproject_idcustomrequirednamestringrequiredenvironmentstringrequiredmin length: 1 · max length: 64 · pattern: ^[a-z0-9][a-z0-9._-]*$retention_daysintegerrequiredgreater than: 0 · max: 9007199254740991status"active" | "suspended"requiredwrite_keystringrequiredcreated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$updated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$has_morebooleanrequiredGet dataset
GET
/v1/projects/{project_id}/datasets/{dataset_id}Path parameters
project_idcustomrequireddataset_idcustomrequiredQuery parameters
No query parameters
Response
9 fields
idcustomrequiredproject_idcustomrequirednamestringrequiredenvironmentstringrequiredmin length: 1 · max length: 64 · pattern: ^[a-z0-9][a-z0-9._-]*$retention_daysintegerrequiredgreater than: 0 · max: 9007199254740991status"active" | "suspended"requiredwrite_keystringrequiredcreated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$updated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Update dataset
PATCH
/v1/projects/{project_id}/datasets/{dataset_id}Path parameters
project_idcustomrequireddataset_idcustomrequiredRequest body
namestringoptionalmin length: 1 · max length: 256environmentstringoptionalmin length: 1 · max length: 64 · pattern: ^[a-z0-9][a-z0-9._-]*$retention_daysintegeroptionalmin: 1 · max: 3650status"active" | "suspended"optionalResponse
9 fields
idcustomrequiredproject_idcustomrequirednamestringrequiredenvironmentstringrequiredmin length: 1 · max length: 64 · pattern: ^[a-z0-9][a-z0-9._-]*$retention_daysintegerrequiredgreater than: 0 · max: 9007199254740991status"active" | "suspended"requiredwrite_keystringrequiredcreated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$updated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Rotate dataset write key
POST
/v1/projects/{project_id}/datasets/{dataset_id}/write-key/rotatePath parameters
project_idcustomrequireddataset_idcustomrequiredRequest body
Response
9 fields
idcustomrequiredproject_idcustomrequirednamestringrequiredenvironmentstringrequiredmin length: 1 · max length: 64 · pattern: ^[a-z0-9][a-z0-9._-]*$retention_daysintegerrequiredgreater than: 0 · max: 9007199254740991status"active" | "suspended"requiredwrite_keystringrequiredcreated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$updated_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Delete dataset
DELETE
/v1/projects/{project_id}/datasets/{dataset_id}Path parameters
project_idcustomrequireddataset_idcustomrequiredQuery parameters
No query parameters
Response
No response body
Events
An immutable analytics fact recorded in a dataset.
List events
GET
/v1/projects/{project_id}/datasets/{dataset_id}/eventsPath parameters
project_idcustomrequireddataset_idcustomrequiredQuery parameters
limitintegeroptionalmin: 1 · max: 100afterstringoptionalnamestringoptionalmin length: 1 · max length: 256start_timestringoptionalformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$end_timestringoptionalformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Response
2 fields
dataobject[]required
dataobject[]requirednamestringrequiredmin length: 1 · max length: 256 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$occurred_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$distinct_idstringoptionalmin length: 1 · max length: 256session_idstringoptionalmin length: 1 · max length: 256sourcestringoptionalmin length: 1 · max length: 128propertiesobjectrequireddefault: {}idcustomrequiredproject_idcustomrequireddataset_idcustomrequiredreceived_atstringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$has_morebooleanrequiredEvent reports
Time-bucketed event counts for one dataset.
Query event report
GET
/v1/projects/{project_id}/datasets/{dataset_id}/reports/eventsPath parameters
project_idcustomrequireddataset_idcustomrequiredQuery parameters
start_timestringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$end_timestringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$interval"hour" | "day"optionaldefault: "day"namestringoptionalmin length: 1 · max length: 256Response
5 fields
start_timestringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$end_timestringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$interval"hour" | "day"requiredtotalintegerrequiredmin: 0 · max: 9007199254740991seriesobject[]required
seriesobject[]requirednamestringrequiredpointsobject[]required
pointsobject[]requiredstart_timestringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$end_timestringrequiredformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$countintegerrequiredmin: 0 · max: 9007199254740991Base URL
https://analytics.socra.cloudEvent ingestion
Write-key event collection for browser, mobile, desktop, and server clients.
Ingest event batch
POST
/v1/events:batchRequest body
write_keystringrequiredmin length: 16 · max length: 256eventsobject[]requiredmin items: 1 · max items: 100
eventsobject[]requiredmin items: 1 · max items: 100namestringrequiredmin length: 1 · max length: 256 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$occurred_atstringoptionalformat: date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$distinct_idstringoptionalmin length: 1 · max length: 256session_idstringoptionalmin length: 1 · max length: 256sourcestringoptionalmin length: 1 · max length: 128idempotency_keystringoptionalmin length: 1 · max length: 128propertiesobjectoptionaldefault: {}Response
2 fields
acceptedintegerrequiredmin: 0 · max: 9007199254740991event_idscustom[]required