Export time series to downloadable files

curl --request POST \
  --url https://api.cloud.corbado.io/v1/observe/timeSeries/export \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromDate": "2026-05-20T00:00:00",
  "toDate": "2026-06-20T00:00:00",
  "interval": "daily",
  "format": "csv",
  "timeSeries": [
    {
      "name": "login-flow-v1",
      "excludeColumns": [
        "t2",
        "osVersion"
      ],
      "engagement": "all"
    }
  ],
  "savedFilterID": "svf-123456",
  "condition": {
    "all": "<array>"
  }
}
'

import requests

url = "https://api.cloud.corbado.io/v1/observe/timeSeries/export"

payload = {
    "fromDate": "2026-05-20T00:00:00",
    "toDate": "2026-06-20T00:00:00",
    "interval": "daily",
    "format": "csv",
    "timeSeries": [
        {
            "name": "login-flow-v1",
            "excludeColumns": ["t2", "osVersion"],
            "engagement": "all"
        }
    ],
    "savedFilterID": "svf-123456",
    "condition": { "all": "<array>" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fromDate: '2026-05-20T00:00:00',
    toDate: '2026-06-20T00:00:00',
    interval: 'daily',
    format: 'csv',
    timeSeries: [
      {name: 'login-flow-v1', excludeColumns: ['t2', 'osVersion'], engagement: 'all'}
    ],
    savedFilterID: 'svf-123456',
    condition: {all: '<array>'}
  })
};

fetch('https://api.cloud.corbado.io/v1/observe/timeSeries/export', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cloud.corbado.io/v1/observe/timeSeries/export",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fromDate' => '2026-05-20T00:00:00',
    'toDate' => '2026-06-20T00:00:00',
    'interval' => 'daily',
    'format' => 'csv',
    'timeSeries' => [
        [
                'name' => 'login-flow-v1',
                'excludeColumns' => [
                                't2',
                                'osVersion'
                ],
                'engagement' => 'all'
        ]
    ],
    'savedFilterID' => 'svf-123456',
    'condition' => [
        'all' => '<array>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloud.corbado.io/v1/observe/timeSeries/export"

	payload := strings.NewReader("{\n  \"fromDate\": \"2026-05-20T00:00:00\",\n  \"toDate\": \"2026-06-20T00:00:00\",\n  \"interval\": \"daily\",\n  \"format\": \"csv\",\n  \"timeSeries\": [\n    {\n      \"name\": \"login-flow-v1\",\n      \"excludeColumns\": [\n        \"t2\",\n        \"osVersion\"\n      ],\n      \"engagement\": \"all\"\n    }\n  ],\n  \"savedFilterID\": \"svf-123456\",\n  \"condition\": {\n    \"all\": \"<array>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloud.corbado.io/v1/observe/timeSeries/export")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fromDate\": \"2026-05-20T00:00:00\",\n  \"toDate\": \"2026-06-20T00:00:00\",\n  \"interval\": \"daily\",\n  \"format\": \"csv\",\n  \"timeSeries\": [\n    {\n      \"name\": \"login-flow-v1\",\n      \"excludeColumns\": [\n        \"t2\",\n        \"osVersion\"\n      ],\n      \"engagement\": \"all\"\n    }\n  ],\n  \"savedFilterID\": \"svf-123456\",\n  \"condition\": {\n    \"all\": \"<array>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloud.corbado.io/v1/observe/timeSeries/export")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fromDate\": \"2026-05-20T00:00:00\",\n  \"toDate\": \"2026-06-20T00:00:00\",\n  \"interval\": \"daily\",\n  \"format\": \"csv\",\n  \"timeSeries\": [\n    {\n      \"name\": \"login-flow-v1\",\n      \"excludeColumns\": [\n        \"t2\",\n        \"osVersion\"\n      ],\n      \"engagement\": \"all\"\n    }\n  ],\n  \"savedFilterID\": \"svf-123456\",\n  \"condition\": {\n    \"all\": \"<array>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "type": "started",
  "exportID": "<string>",
  "series": "<string>",
  "sliceFrom": "<string>",
  "sliceTo": "<string>",
  "rows": 123,
  "bytes": 123,
  "export": {
    "exportID": "tse-123456",
    "status": "pending",
    "createdMs": 1752738240000,
    "fromDate": "<string>",
    "toDate": "<string>",
    "interval": "hourly",
    "format": "csv",
    "timeZone": "Europe/Berlin",
    "timeSeries": [
      {
        "name": "<string>",
        "excludeColumns": [
          "<string>"
        ],
        "engagement": "<string>",
        "columns": [
          "<string>"
        ],
        "customTags": {},
        "columnGuide": {
          "version": 123,
          "columns": [
            {
              "key": "<string>",
              "label": "<string>",
              "description": "<string>",
              "values": "<string>"
            }
          ],
          "notes": [
            "<string>"
          ]
        },
        "file": {
          "name": "<string>",
          "size": 123,
          "checksum": "<string>",
          "rows": 123
        }
      }
    ],
    "completedMs": 1752738240000,
    "expiresAtMs": 1752738240000,
    "sizeBytes": 123,
    "error": "<string>"
  },
  "savedFilter": {
    "status": "none",
    "savedFilterID": "<string>",
    "version": 123,
    "name": "<string>",
    "source": "default",
    "missing": [
      {
        "dimension": "<string>",
        "tag": "<string>"
      }
    ]
  }
}

{
  "error": {
    "message": "Validation failed",
    "details": [
      {
        "field": "projectID",
        "message": "required"
      }
    ]
  }
}

Data exports

Export time series to downloadable files

Exports one or more precalculated time series as CSV or Parquet, one file per series, using a shared date range and interval. Each row represents a non-zero time-bucket and dimension combination, with time, timeLocal, retained dimensions in canonical order and value. time is the UTC bucket start (RFC 3339 in CSV, timestamp in Parquet); timeLocal uses the project timezone reported in timeZone. Dimensions in excludeColumns are collapsed and their values summed, as when omitted from groupBy.

Generation runs while the request remains open. The response streams progress as application/x-ndjson; the final event is completed with the export descriptor or failed. Retrieve files using the download-link endpoint before expiresAtMs.

Validation errors return a regular JSON error before streaming starts. Exceeding the project’s concurrent-export limit or daily quota returns HTTP 429.

Required API key permission: observe:timeSeries:read.

POST

observe

timeSeries

export

Export time series to downloadable files

curl --request POST \
  --url https://api.cloud.corbado.io/v1/observe/timeSeries/export \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fromDate": "2026-05-20T00:00:00",
  "toDate": "2026-06-20T00:00:00",
  "interval": "daily",
  "format": "csv",
  "timeSeries": [
    {
      "name": "login-flow-v1",
      "excludeColumns": [
        "t2",
        "osVersion"
      ],
      "engagement": "all"
    }
  ],
  "savedFilterID": "svf-123456",
  "condition": {
    "all": "<array>"
  }
}
'

import requests

url = "https://api.cloud.corbado.io/v1/observe/timeSeries/export"

payload = {
    "fromDate": "2026-05-20T00:00:00",
    "toDate": "2026-06-20T00:00:00",
    "interval": "daily",
    "format": "csv",
    "timeSeries": [
        {
            "name": "login-flow-v1",
            "excludeColumns": ["t2", "osVersion"],
            "engagement": "all"
        }
    ],
    "savedFilterID": "svf-123456",
    "condition": { "all": "<array>" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fromDate: '2026-05-20T00:00:00',
    toDate: '2026-06-20T00:00:00',
    interval: 'daily',
    format: 'csv',
    timeSeries: [
      {name: 'login-flow-v1', excludeColumns: ['t2', 'osVersion'], engagement: 'all'}
    ],
    savedFilterID: 'svf-123456',
    condition: {all: '<array>'}
  })
};

fetch('https://api.cloud.corbado.io/v1/observe/timeSeries/export', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cloud.corbado.io/v1/observe/timeSeries/export",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fromDate' => '2026-05-20T00:00:00',
    'toDate' => '2026-06-20T00:00:00',
    'interval' => 'daily',
    'format' => 'csv',
    'timeSeries' => [
        [
                'name' => 'login-flow-v1',
                'excludeColumns' => [
                                't2',
                                'osVersion'
                ],
                'engagement' => 'all'
        ]
    ],
    'savedFilterID' => 'svf-123456',
    'condition' => [
        'all' => '<array>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloud.corbado.io/v1/observe/timeSeries/export"

	payload := strings.NewReader("{\n  \"fromDate\": \"2026-05-20T00:00:00\",\n  \"toDate\": \"2026-06-20T00:00:00\",\n  \"interval\": \"daily\",\n  \"format\": \"csv\",\n  \"timeSeries\": [\n    {\n      \"name\": \"login-flow-v1\",\n      \"excludeColumns\": [\n        \"t2\",\n        \"osVersion\"\n      ],\n      \"engagement\": \"all\"\n    }\n  ],\n  \"savedFilterID\": \"svf-123456\",\n  \"condition\": {\n    \"all\": \"<array>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloud.corbado.io/v1/observe/timeSeries/export")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fromDate\": \"2026-05-20T00:00:00\",\n  \"toDate\": \"2026-06-20T00:00:00\",\n  \"interval\": \"daily\",\n  \"format\": \"csv\",\n  \"timeSeries\": [\n    {\n      \"name\": \"login-flow-v1\",\n      \"excludeColumns\": [\n        \"t2\",\n        \"osVersion\"\n      ],\n      \"engagement\": \"all\"\n    }\n  ],\n  \"savedFilterID\": \"svf-123456\",\n  \"condition\": {\n    \"all\": \"<array>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloud.corbado.io/v1/observe/timeSeries/export")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fromDate\": \"2026-05-20T00:00:00\",\n  \"toDate\": \"2026-06-20T00:00:00\",\n  \"interval\": \"daily\",\n  \"format\": \"csv\",\n  \"timeSeries\": [\n    {\n      \"name\": \"login-flow-v1\",\n      \"excludeColumns\": [\n        \"t2\",\n        \"osVersion\"\n      ],\n      \"engagement\": \"all\"\n    }\n  ],\n  \"savedFilterID\": \"svf-123456\",\n  \"condition\": {\n    \"all\": \"<array>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "type": "started",
  "exportID": "<string>",
  "series": "<string>",
  "sliceFrom": "<string>",
  "sliceTo": "<string>",
  "rows": 123,
  "bytes": 123,
  "export": {
    "exportID": "tse-123456",
    "status": "pending",
    "createdMs": 1752738240000,
    "fromDate": "<string>",
    "toDate": "<string>",
    "interval": "hourly",
    "format": "csv",
    "timeZone": "Europe/Berlin",
    "timeSeries": [
      {
        "name": "<string>",
        "excludeColumns": [
          "<string>"
        ],
        "engagement": "<string>",
        "columns": [
          "<string>"
        ],
        "customTags": {},
        "columnGuide": {
          "version": 123,
          "columns": [
            {
              "key": "<string>",
              "label": "<string>",
              "description": "<string>",
              "values": "<string>"
            }
          ],
          "notes": [
            "<string>"
          ]
        },
        "file": {
          "name": "<string>",
          "size": 123,
          "checksum": "<string>",
          "rows": 123
        }
      }
    ],
    "completedMs": 1752738240000,
    "expiresAtMs": 1752738240000,
    "sizeBytes": 123,
    "error": "<string>"
  },
  "savedFilter": {
    "status": "none",
    "savedFilterID": "<string>",
    "version": 123,
    "name": "<string>",
    "source": "default",
    "missing": [
      {
        "dimension": "<string>",
        "tag": "<string>"
      }
    ]
  }
}

{
  "error": {
    "message": "Validation failed",
    "details": [
      {
        "field": "projectID",
        "message": "required"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server.

Body

application/json

fromDate

string

required

Range start in UTC, formatted as YYYY-MM-DDTHH:MM:SS without a timezone suffix. Convert project-local selections to UTC before calling. Applies to every exported time series.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

Example:

"2026-05-20T00:00:00"

toDate

string

required

Exclusive range end in UTC, formatted as YYYY-MM-DDTHH:MM:SS without a timezone suffix. Must be after fromDate; the maximum range depends on the interval.

Pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$

Example:

"2026-06-20T00:00:00"

interval

string

required

Aggregation interval, applies to every exported time series. One of: hourly, daily, monthly.

Example:

"daily"

format

string

required

File format, applies to every exported time series. One of: csv, parquet.

Example:

"csv"

timeSeries

object[]

required

Time series to export, one file each. Names must be unique within the request.

Required array length: 1 - 20 elements

Show child attributes

savedFilterID

string

Saved filter to apply (format svf-<number>), or none for unfiltered data. Omitted: the project's default saved filter (unfiltered when none is set). A saved filter given here replaces the default; it is never combined with it. Series the filter is not applicable to are exported unfiltered.

Example:

"svf-123456"

condition

all · object

Filter on the series' dimensions and custom tags, in the condition format of saved filters (saved-filter-v1, see observeSavedFilterCondition), e.g. {"tag":"market","notIn":["de",null]}. Combined (AND) with the saved filter. Unlike the saved filter, a condition that reads a dimension or custom tag one of the series does not carry is rejected (400) before the export starts. The limits of saved filter definitions apply (6 levels, 50 dimension or tag conditions, 200 values per list).

all
any
not
dimension
tag

Show child attributes

Response

Newline-delimited JSON progress stream; the final line carries the export descriptor.

One line of the export progress stream.

type

enum<string>

required

Available options:

started,

progress,

completed,

failed

exportID

string

required

series

string

Time series name the progress event refers to

sliceFrom

string

Start of the time slice just written (progress)

sliceTo

string

Exclusive end of the time slice just written (progress)

rows

integer<int64>

Rows written for this series so far (progress)

bytes

integer<int64>

Bytes written for this series so far (progress)

export

object

Show child attributes

savedFilter

object

The saved filter the exported series were read with (completed and failed). notApplicable when a series does not carry what the filter reads (missing); those series were exported unfiltered.

Show child attributes

Overview

Corbado Observe

Corbado Connect

Export time series to downloadable files

Authorizations

Body

Response