Export users

Export users from a workspace.

GET

https://api.croct.io/export/users

Example

Here is an example of how to export events:

import {Configuration, ExportApi} from '@croct/export';
async function exportUsers(): Promise<void> {const api = new ExportApi(new Configuration({apiKey: '<API KEY>'}));
let cursor: string | undefined = undefined;let running = true;
while (running) {const {data: {items: users, nextCursor}} = await api.exportUsers({pageSize: 100,cursor: cursor,start: 1440990000000,end: 1441076400000,});
console.log(users);
cursor = nextCursor;running = users.length > 0;}}

Headers

This endpoint requires the following HTTP headers:

X-Api-Key string: The API key of the application associated with the workspace from which to export users.

Parameters

This endpoint accepts the following query parameters:

start(optional) integer: The earliest session close time to include, in milliseconds since epoch.
Only sessions closed at or after this time are included.
end(optional) integer: The latest session close time to include, in milliseconds since epoch.
Only sessions closed before this time are included. If not provided, there is no upper time limit.
pageSize(optional) integer: The maximum number of sessions returned per request.
Must be between 1 and 1000.
Default:100
cursor(optional) string: A cursor for retrieving the next page of results.
If omitted, export starts from the beginning of the specified time window.

Response

This endpoint returns a JSON response with the following properties:

data object

The response containing exported sessions and pagination information.

items object[]

The list of exported sessions.

sessionId string

The ID that uniquely identifies the session across the application in UUID format.

userId string

The ID that uniquely identifies the user across the workspace in UUID format.

parentId string|null

The ID of the session that superseded this session.

Usually set when a user is identified, causing the current anonymous session to end and a new identified session to begin.

externalUserId string|null

The external user ID used to identify the user on the application side.

Always null for anonymous users.

window object

The time window covering the first and last event of the session.

start integer: The session start timestamp in milliseconds since epoch.
end integer: The session end timestamp in milliseconds since epoch.

closeTime integer

The time from which the session is closed for new events.

May be extended if new events arrive before the session is fully closed.

referrer string|null

The URI of the content that linked to the page that started the session.

landingPageUrl string|null

The page URL that started the session.

campaign object|null

The available information about the campaign.

name string|null: A unique identifier for the campaign. It is usually a short string, such as "summer-sale" or "new-product-launch".
source string|null: The advertiser, site, or publication generating the traffic. For example, "google", "facebook", or "newsletter".
medium string|null: The advertising or marketing channel used to reach the user. For example, "email", "video", or "social".
content string|null: An identification of the specific ad or content the user interacted with. For example, "main-banner" or "newsletter-cta".
term string|null: The keyword or term that triggered the ad. For example, "running shoes" or "tennis racket".

location object|null

The available information about the user's location.

continent string|null

The continent code where the location is situated. The possible values are:

Value	Description
AF	Africa
AN	Antarctica
AS	Asia
EU	Europe
NA	North America
OC	Oceania
SA	South America

country string|null

The country code following the ISO 3166-1 alpha-2 standard, in upper case.

For example, "US" for United States.

region object|null

The primary administrative division within the country, such as a state or province.

name string: The name of the region in English.
For example, "California" or "New York".
code string|null: The code is based on the ISO 3166-2 standard or official codes whenever available, in upper case.
For example, "CA" for California.

city string|null

The incorporated city or town political entity.

For example, "New York", "Mexico City" or "São Paulo".

district string|null

The district, county, or department within the region.

For example, "Los Angeles County" or "Greater London".

timezone string|null

The time zone name as specified in the IANA Time Zone Database.

For example, "America/New_York" or "America/Sao_Paulo".

coordinates object|null

The geographic coordinates of the location.

latitude number: The latitude of the location as a decimal.
For example, 36.7783 or -23.5475.
longitude number: The longitude of the location as a decimal.
For example, 119.4179 or -46.63611.

source string

The sources of location information. The possible values are:

Value	Description
IP	Location inferred based on the IP address.
GPS	Location inferred based on the GPS data.
BROWSER	Location inferred based on the browser information.
INPUT	Location provided by the application.
UNKNOWN	An unknown source.

currency object|null

The official currency used in the location.

name string|null: The name of the currency in English.
For example, "US Dollar" or "Real".
code string|null: The currency code following the ISO 4217 standard, in upper case.
For example, "USD" or "BRL".

phoneCode string|null

The international dialing code for this location.

For example, "+1" for the United States or Canada, or "+55" for Brazil.

population number|null

The approximate population within the boundaries of the returned location.

If the location refers to a city, this value reflects the city's population. If it refers to a broader area, such as a region, it reflects the population of that region.

postalCode string|null

The postal or ZIP code associated with the location.

The value follows a valid format (e.g., "90210", "SW1A 1AA", or "28430-000"), but may represent an approximate or example code for the region rather than an exact or specific address. In some areas, it may reflect the beginning of a postal range.

languages array<string>|null

A list of locale codes of the languages spoken in the location as specified in the ISO 639-1 and ISO 3166-1.

For example, ["en", "en-CA", "fr-CA"] indicates that English and French are spoken in Canada, with English being more prevalent.

tags array<string>

One or more tags describing the location, such as natural features or climate.

For example, a lake in a warm, touristic area might include tags like "warm", "lake" and "tourism".

Tags related to the type of place or area:

Tag	Description
urban	Related to cities or densely populated areas
residential	Areas where housing and living spaces are concentrated
rural	Countryside or sparsely populated regions outside urban centers
remote	Locations distant from major settlements or infrastructure
park	Public or protected areas with greenery or open space
island	Land surrounded by water on all sides

Tags denoting social roles, institutions, and public services:

Tag	Description
government	Locations related to public services, institutions, or administration
politics	Places associated with political activity or governance
military	Locations used for defense, training, or armed service operations
religion	Sites with religious or spiritual significance
education	Places where people study and learn

Tags related to economic activity:

Tag	Description
business	Areas with commercial presence or economic activity
industry	Zones involving manufacturing, logistics, or production
agriculture	Areas with fields, pastures, or crops

Tags related to transportation, utilities, and built environments:

Tag	Description
transport	Locations supporting transit or logistics
facility	Places built for specific purposes, often supporting operations or services
waterway	Navigable or managed water routes such as rivers or canals
airport	Locations related to aircraft takeoff and landing
road	Infrastructure for vehicular travel
railway	Locations involving rail transport infrastructure
seaport	Ports where ships may dock, load, or unload goods or passengers

Tags for areas commonly used for sports and outdoor activities:

Tag	Description
fishing	Areas where fishing or related activity may take place
surfing	Coastal areas with waves that may support surfing
swimming	Areas where people may swim or engage with water safely
hiking	Outdoor spaces where hiking might occur
skiing	Areas where snow allows skiing or similar activities

Tags highlighting cultural, recreational, or scenic appeal:

Tag	Description
entertainment	Places that can offer cultural or recreational activities
scenery	Locations appreciated for their natural beauty or view
landmark	Notable spots or features that help identify a place
recreation	Areas intended for outdoor activities, sports, or leisure
tourism	Places people visit for culture, nature, or history

Tags describing natural features and landscapes:

Tag	Description
mountain	Elevated terrain rising above surroundings
lake	Bodies of still water surrounded by land
river	Naturally flowing body of water that may lead to lakes or oceans
canyon	Natural formations shaped by erosion
desert	Dry regions with little rainfall or vegetation
ocean	Coastal or open-sea areas facing large saltwater bodies
coast	Edges of land meeting a sea or ocean
beach	Shoreline with sand or pebbles, often near water bodies
forest	Areas with dense tree cover

Tags related to climate and weather conditions:

Tag	Description
warm	Regions with generally tropical or temperate climates
cold	Regions characterized by low temperatures
snowy	Areas with frequent snow or icy conditions

client object

The available information about the client.

device object

The device used by the client.

name string|null

The name of the device. For example, "iPhone 11 Pro" or "MacBook Pro".

vendor string|null

The vendor or manufacturer of the device. For example, "Apple" or "Samsung".

category string

The category of the device. The possible values are:

Value	Description
desktop	A desktop computer.
tablet	A tablet device.
mobile	A mobile phone.
bot	Bots or crawlers.
other	Any other device.
unknown	An unknown device.

operatingSystem object

The operating system of the device.

name string|null: The name of the operating system. For example, "iOS", "Android", or "Windows".
version string|null: The operating system's version. For example, "10.0.18363", "13.3", or "10".

browser object

The browser used by the client.

name string|null

The browser's name. For example, "Chrome", "Safari", or "Firefox".

version string|null

The browser's version. For example, "78.0.3904.108", "13", or "71.0".

type string

The browser type. The possible values are:

Value	Description
web	A standard web browser.
in-app	A browser embedded in an application.
crawler	A search engine bot or crawler.
other	Any other browser, like proxies or feed readers.
unknown	An unknown browser type.

attributes object

Custom attributes associated with the session.

statistics object

Aggregated session statistics.

pageViews integer: The total number of page views.
tabViews integer: The total number of tab views.
orders integer: The total number of orders placed.

nextCursor string

A cursor for retrieving the next page of results.

If omitted, export starts from the beginning of the specified time window.

Example response

Here is an example of a JSON response from this endpoint:

{  "items": [    {      "organizationId": "e3e8db14-f4fb-427f-a4a3-cfd763397a83",      "workspaceId": "5b79b878-b826-4f38-9813-7f69c7995bb3",      "userId": "e9fc50b8-1773-42a0-ac51-fab9a1ee48de",      "externalUserId": "john-doe-acme-123",      "profile": {        "firstName": {          "value": "John",          "timestamp": 0        },        "lastName": {          "value": "Doe",          "timestamp": 0        },        "birthDate": {          "value": "1990-01-01",          "timestamp": 0        },        "gender": {          "value": "MALE",          "timestamp": 0        },        "email": {          "value": "john@acme.com",          "timestamp": 0        },        "alternateEmail": {          "value": "john@example.com",          "timestamp": 0        },        "phone": {          "value": "000000000",          "timestamp": 0        },        "alternatePhone": {          "value": "999999999",          "timestamp": 0        },        "address": {          "value": {            "street": "Av. Paulista, 2202",            "district": "Bela Vista",            "city": "São Paulo",            "region": "São Paulo",            "country": "Brazil",            "postalCode": "12345-678"          },          "timestamp": 0        },        "avatar": {          "value": "https://example.com/avatar",          "timestamp": 0        },        "company": {          "value": "Acme",          "timestamp": 0        },        "companyUrl": {          "value": "https://acme.com",          "timestamp": 0        },        "jobTitle": {          "value": "CEO",          "timestamp": 0        },        "interests": {          "value": ["business", "politics"],          "timestamp": 0        },        "activities": {          "value": ["content-share", "newsletter-subscription"],          "timestamp": 0        },        "customAttributes": {          "plan": {            "value": "Pro",            "timestamp": 0          },          "subscriptionDate": {            "value": "2025-01-01",            "timestamp": 0          }        }      },      "statistics": {        "sessions": 1,        "orders": 2      },      "lastModifiedTime": 1000    }  ],  "nextCursor": "eyJzZXNzaW9uSWQiOiIxMjM0NSIsImNsb3NlVGltZSI6MTYwOTQ1OTMwMDAwMH0"}