Exporting evaluations

The Scorecards feature of Olos Analytics supports the evaluation of interactions it has ingested by answering questions about the conversation and providing scores. The answers can be provided by AI or manually by a human or both. This page explains how you can get access to these evaluations programmatically.

Overview

  • You send an HTTP request to the API specifying filters and a callback URL.
  • The API replies immediately with an export ID.
  • Olos Analytics generates a .gz file containing the evaluations in JSON Lines format and stores it internally.
  • Olos Analytics invokes your callback URL passing a download URL.
  • You download the evaluations file using the download URL.

Request

  • Obtain an access token as described in Authentication.

  • Send a POST request like in this example:

curl --request POST \
     --url https://<tenant ID>.api-prod01.olos.live/analytics/scorecards/export \
     --header 'Authorization: Bearer <access token>' \
     --data '<payload>'

where payload looks like this example:

{
    "filter": {
        "startDate": "2025-05-01",
        "endDate": "2025-05-31",
        "orgCode": "demo",
        "formId": "019a3b86-702a-7a39-971a-376e6aa2aaa1",
        "formVersion": 1,
        "isFinished": true
    },
    "callbackURL": "https://api.pixeltrends.com.br/import?id=a7d23c5ff43"
}

Only startDate and endDate are required.

Scenarios

The filter is flexible enough to support multiple scenarios depending on how specific you want to be when exporting evaluations:

Scenario orgCode formId formVersion
Evaluations from a specific form and version specify specify specify
Evaluations from any form in a given organization specify omit omit
Evaluations from any form in any organization (*) omit omit omit

If you want to specify a form and/or an organization but you don't know their ID/code, please reach out to Olos at opd@olos.com.br.

Rules

  • startDate and endDate are the only required attributes.

  • The number of days between startDate and endDate (inclusive) must be between 1 and 40 (inclusive).

  • If you want to specify a form then you must provide orgCode, formId and formVersion. The form must belong to the organization.

  • If orgCode is provided but not formId and formVersion then evaluations from any form in the organization are exported.

  • If no orgCode, formId and formVersion are provided then evaluations from any form of any organization are exported (*)

(*) the list of organizations you have access to depends on the configuration of your application account in Olos Analytics. If you think you should have access to an organization you currently don't have, please reach out to Olos at opd@olos.com.br.

Response

In case of success, you will get an 200 (OK) response with a body like this:

{
    "exportId": "ayw81a48gcCaAjTt1FXEjG"
}

It means your request has been queued and will be processed as soon as possible. It can take several seconds to a few minutes, depending on the volume of data that is being exported and the current load on Olos Analytics.

Callback

Once your export is finished, Olos Analytics will send a POST HTTP request to the callback URL you have provided, passing a JSON body like in the following example:

{
    "exportId": "ayw81a48gcCaAjTt1FXEjG",
    "status": "success",
    "requestedAt": "2025-10-31T23:06:54Z",
    "startedAt": "2025-10-31T23:07:12Z",
    "finishedAt": "2025-10-31T23:09:34Z",
    "evaluationsCount": 42,
    "bytesCount": 645122,
    "downloadURL": "https://s3.aws...?token=..."
}

It means Olos Analytics has created a .gz JSON Lines file with 42 evaluations that you can download using the downloadURL using a simple GET.

The download URL is valid for 6 hours.

If the export process fails, the status will be failed and you won't get a download URL.

Fallback

At any time you can check the status of your export request by sending a GET rquest like in the following example:

curl --request GET \
     --url https://<tenant ID>.api-prod01.olos.live/analytics/scorecards/export/<exportId> \
     --header 'Authorization: Bearer <access token>' \

The response body is in the same format as the callback payload you have seen above, with the additional attribute callbackResult, which describes the respose Olos Analytics has received from your callback URL.

Status

Status Description
queued The export request is valid, it has been queued and it will be processed as soon as possible.
running The export process is running. The next status can be success or failed.
success The export process has finished successfully. This is a final status.
failed The export process has failed. This is a final status.

Data format

The downloaded file containing the evaluations follows this naming convention:

olos-analytics-scorecards-YYYY_MM_DD_HH_MI_SS-<exportId>.jsonl.gz

The timestamp is the time when the export has been started.

Example: olos-analytics-scorecards-2025_10_31_23_06_54-ayw81a48gcCaAjTt1FXEjG.jsonl.gz

The .jsonl file is a regular unix-like text file containing one evaluation per line in JSON format.

You can download a sample.jsonl to see how it looks like.

Then you can use cat sample.jsonl | jq to pretty-print it.

Callback server simulator

server is a 9MB linux binary that you can use to test the integration. It listens on the given http port (8080 by default) and, for each callback received, prints the JSON payload, downloads the export file and unzips it in your current directory, printing the file name and some performance-related figures.

Reach out to Olos at opd@olos.com.br to obtain a copy of the server binary.