# Export sessions

Export sessions from an application.

```
GET https://api.croct.io/export/session
```

## Example

Here is an example of how to export sessions:

**JavaScript**

```js
const url = new URL('https://api.croct.io/export/session');
url.searchParams.append('start', '1440990000000');
url.searchParams.append('end', '1441076400000');
url.searchParams.append('pageSize', '100');

const response = await fetch(url, {
  headers: {
    'X-Api-Key': '<API KEY>',
  },
});

const {items, nextCursor} = await response.json();
```

**cURL**

```bash
curl -X GET 'https://api.croct.io/export/session' \
  -H 'X-Api-Key: <API KEY>' \
  -G \
  --data-urlencode 'start=1440990000000' \
  --data-urlencode 'end=1441076400000' \
  --data-urlencode 'pageSize=100'
```

## Headers

This endpoint requires the following HTTP headers:

- `X-Api-Key`: `string`

  The [API key](/explanation/application/api-keys) of the application from which to export sessions.

## Parameters

This endpoint accepts the following query parameters:

- `start`: `integer` (optional)

  The earliest session close time to include, in milliseconds since epoch.

  Only sessions closed at or after this time are included.

- `end`: `integer` (optional)

  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`: `integer` (optional) (default: 100)

  The maximum number of sessions returned per request.

  Must be between 1 and 1000.

- `cursor`: `string` (optional)

  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`: `Array<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`

      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`

      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](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard, in upper case.

        For example, "US" for United States.

      - `region`: `object`

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

        - `name`: `string|null`

          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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).

        For example, "America/New\_York" or "America/Sao\_Paulo".

      - `coordinates`: `object`

        The geographic coordinates of the location.

        - `latitude`: `number|null`

          The latitude of the location as a decimal.

          For example, `36.7783` or `-23.5475`.

        - `longitude`: `number|null`

          The longitude of the location as a decimal.

          For example, `119.4179` or `-46.63611`.

      - `source`: `string|null`

        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`

        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](https://en.wikipedia.org/wiki/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>`

        A list of locale codes of the languages spoken in the location as specified in the [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) and [ISO 3166-1](https://en.m.wikipedia.org/wiki/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|null`

          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|null`

          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`

    An opaque cursor for retrieving the next page of results.

    The value is an empty string when there are no more results. Treat it as opaque and pass it back unchanged on the next request.

### Example response

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

```json
{
  "items": [
    {
      "sessionId": "12345678-1234-1234-1234-123456789012",
      "userId": "87654321-4321-4321-4321-210987654321",
      "parentId": null,
      "externalUserId": "user-123",
      "window": {
        "start": 1440990000000,
        "end": 1441000000000
      },
      "closeTime": 1441001000000,
      "referrer": "https://google.com",
      "landingPageUrl": "https://example.com/home",
      "campaign": {
        "name": "summer-sale",
        "source": "google",
        "medium": "cpc",
        "content": "banner-ad",
        "term": "running shoes"
      },
      "location": {
        "source": "IP",
        "continent": "NA",
        "country": "US",
        "region": {
          "name": "California",
          "code": "CA"
        },
        "district": "San Francisco County",
        "city": "San Francisco",
        "timezone": "America/Los_Angeles",
        "coordinates": {
          "latitude": 37.7749,
          "longitude": -122.4194
        },
        "currency": {
          "name": "US Dollar",
          "code": "USD"
        },
        "phoneCode": "+1",
        "population": 873965,
        "postalCode": "94103",
        "languages": ["en-US"],
        "tags": ["city"]
      },
      "client": {
        "device": {
          "name": "iPhone 12",
          "vendor": "Apple",
          "category": "MOBILE",
          "operatingSystem": {
            "name": "iOS",
            "version": "14.4"
          }
        },
        "browser": {
          "name": "Safari",
          "version": "14.0",
          "type": "WEB"
        }
      },
      "attributes": {
        "customField": "value"
      },
      "statistics": {
        "pageViews": 5,
        "tabViews": 2,
        "orders": 1
      }
    }
  ],
  "nextCursor": "eyJzZXNzaW9uSWQiOiIxMjM0NSIsImNsb3NlVGltZSI6MTYwOTQ1OTMwMDAwMH0"
}
```