This page describes how to export activity data and logs from the platform. The Explore/Telemetry module provides a comprehensive suite of reporting APIs designed to extract granular activity logs. This guide outlines how to interface with the APIs to programmatically retrieve key workflow metrics, including status transitions, task assignments, and time tracking data. The APIs available are as follows:

Annotation Status Change
Working Time (Item Daily Hours)
Assignment History

Authentication

All three APIs are authenticated with a Team SDK Token, obtained from Team Setup. Set the API key as the auth value in the request header, and set authtype to sdk. Calls can be made with Postman or any HTTP client capable of sending POST and GET requests.

Annotation Status Change API

Generates and downloads a report of annotation status transitions (e.g., item status changed from "In Progress" to "Quality Check").

📘
Telemetry must be activated for the organization. If the token is valid but Telemetry is not activated, the API returns "Access denied." in the response.

Step 1 — Generate the report

Send a call to the following endpoint with the POST method by using authentication as mentioned here.

https://explore-service.superannotate.com/api/v1/reports/create/annotation-statuses

Request body:

{
    "name": "Custom Report name set by User",
    "filters": {
        "period": {
            "from": "2026-03-08",
            "to": "2026-03-11"
        },
        "projects": ["project1", "project2"],
        "fromStatuses": ["status1", "status2"],
        "toStatuses": ["status3", "status4"]
    }
}

Field notes:

period — Date range. Maximum 31 days. Required.
projects — Current project names, up to 5. Optional; if empty, all projects are included. An invalid, renamed, or deleted name stops report generation with: "Project with name [project name] does not exist."
fromStatuses — Status names to filter transitions from. Optional; if empty, all "from" statuses are included. Matched against the raw log, so a status renamed after an event occurred won't match older logs. Invalid names are ignored.
toStatuses — Status names to filter transitions to. Same rules as fromStatuses.
name — Must be unique. A duplicate name returns: "This report name already exists."

Response:

{
    "id": "04419826771fe93d31183521b0840c237df29ec3d9541186b5f6b141370190f3",
    "name": "Custom Report name set by User",
    "type": 7,
    "filters": {
        "period": { "from": "2026-03-08T00:00:00.000Z", 
"to": "2026-03-11T00:00:00.000Z" },
        "projects": ["project1", "project2"],
        "fromStatuses": ["status1", "status2"],
        "toStatuses": ["status3", "status4"]
    },
    "status": 1
}

Step 2 — Poll for the download URL

Send a call to the following endpoint with the GET method by using authentication as mentioned here.

https://explore-service.superannotate.com/api/v1/reports/download/{report_id}

Use the id returned in Step 1 as the {report_id} in the endpoint. While the report is being generated, the response status is "In progress". Once it’s ready, the response will contain a download URL valid for 2 hours.

Response:

{
    "downloadUrl": "https://annotate-online-assets.s3.amazonaws.com/reports/ANNOTATION_STATUS_CHANGE/{reportId}/sdk/{Report_Name}.csv?AWSAccessKeyId=EXAMPLEACCESSKEYID123&Expires=1735689600&Signature=example%2Bsignature%2Bplaceholder%3D&x-amz-security-token=EXAMPLE_SESSION_TOKEN_PLACEHOLDER_DO_NOT_USE_REAL_VALUES_HERE"
}

Step 3 — Download the CSV

Open the URL from Step 2 in a browser, or fetch it with an HTTP client, to download the report as a CSV. If all filters are valid but no matching data exists, an empty CSV will be generated.

Response Data Reference

Each row represents one annotation status transition:

Column	Description
Transition Date	Date and time that the transition occurred (UTC), inclusive of the filter's start and end dates.
Project	Current project name. Shown as `"Deleted project"` if deleted after the transition was logged.
Item	Name of the item whose status changed.
User	Email of the user who performed the status change.
Role	Name of the user's role at the time of the change.
Status From	Annotation status before the transition.
Status To	Annotation status after the transition.
Item Creation Date	Datetime the item was created in the project.

📘
Error Reference

Invalid, renamed, or deleted project name: "Project with name [project name] does not exist."

Telemetry not activated for the organization: "Access denied."

Valid filters, no matching data: Empty CSV is generated (not an error).

Working Time API (Item Daily Hours)

Generates and downloads a report showing, for each day, how much time each user spent working on specific items.

🚧
Telemetry must be activated for the organization. If the token is valid but Telemetry is not activated, the API returns "Access denied." in the response.

Step 1 — Generate the report

Send a call to the following endpoint with the POST method by using authentication as mentioned here.

https://explore-service.superannotate.com/api/v1/reports/create/hours-items

Request body:

{
    "name": "Custom Report name set by User",
    "filters": {
        "period": {
            "from": "2026-03-01",
            "to": "2026-03-20"
        },
        "projects": ["Project name 1", "Project 2"],
        "users": ["[email protected]"],
        "roles": ["Annotator"]
    }
}

Field notes:

period — Date range ‘from’ and ‘to’ inclusive. Maximum 31 days. Required.
projects — Current project names, up to 5. Optional; if empty, all projects are included. An invalid, renamed, or deleted name stops report generation with: "Project with name [project name] does not exist."
users — User emails to filter working hours, up to 10. Optional; if empty, all available users working time will be returned. Invalid names are silently ignored.
roles — User roles to filter working hours, up to 5. Optional; if empty, all available roles working time will be returned.
name — Must be unique. A duplicate name returns: "This report name already exists."

Response:

{
    "id": "177544ef72b9f14d4509a980e9aedcfc7d57d5dd8c775bde4738384451fe277b",
    "name": "Custom Report name set by User",
    "type": 4,
    "filters": {
        "period": { "from": "2026-03-01T00:00:00.000Z", 
 "to": "2026-03-20T00:00:00.000Z" },
        "projects": ["Project name 1", "Project 2"],
        "users": ["[email protected]"],
        "roles": ["Annotator"]
    },
    "status": 1
}

Step 2 — Poll for the download URL

Send a call to the following endpoint with the GET method by using authentication as mentioned here.

https://explore-service.superannotate.com/api/v1/reports/download/{report_id}

Use the id returned in Step 1 as the report_id} in the endpoint. While the report is being generated, the response status is "In progress". Once ready, the response will contain a download URL valid for 2 hours.

Response:

{
    "downloadUrl": "https://assets-bucket-ao-dev.s3.us-west-2.amazonaws.com/reports/{report_type}/{report_id}/sdk/{report_name}.csv?AWSAccessKeyId=EXAMPLEACCESSKEYID123&Expires=1735689600&Signature=example%2Bsignature%2Bplaceholder%3D&x-amz-security-token=EXAMPLE_SESSION_TOKEN_PLACEHOLDER_DO_NOT_USE_REAL_VALUES_HERE"
}

Step 3 — Download the report

Open the URL from Step 2 in a browser, or fetch it with an HTTP client, to download the report as a CSV. If all filters are valid but no matching data exists, an empty CSV is generated.

Response Data Reference

Column	Description
Date	Date the item was worked on (YYYY-MM-DD). Cannot be empty.
Team	The team's name.
Project	The project's name. Shown as "Deleted project" if deleted after the data was logged.
Folder	The folder's name. Shown as "Deleted folder" if deleted after the data was logged.
Item	The item's name.
Current Status	The item's annotation status at the moment the report is generated.
User	Email of the user.
Role	Role assigned to the user while working the item. If renamed since, the report shows the old name for data generated before the rename.
Worked Duration	Minutes the user spent working in the editor within the filtered date range. The report will not show items with zero duration.

📘
Error Reference

DUPLICATE_REPORT: "This report name already exists." - Report name is not unique.

INVALID_REPORT_PERIOD: "Invalid report period. The period must be between 0 and 31 days." - Date range out of bounds.

INVALID_REPORT_FILTER: "Role with name [role name] does not exist." "Project with name [project name] does not exist." - Invalid filter value.

INPUT: "filters.projects must contain less than or equal to 5 items" (same pattern for other filters) - Filter array too long.

NOT_EXISTS: "Cannot Download a report that doesn't exists, or is not ready for download" - Report ID invalid or not yet generated.

FORBIDDEN: "Not authorized." - Incorrect team token/ID.

JOB_IN_PROGRESS: "Report generation still in progress" - Report not ready yet.

Assignment History API

Retrieves the full assignment/reassignment history for one or more items — no report generation step required; this is a direct lookup.

📘
There is NO need to have Telemetry activated for the organization. This event’s logging is independent from the Telemetry system.

Step 1 — Send the request

Send a call to the following endpoint with the POST method by using authentication as mentioned here.

https://explore-service.superannotate.com/api/v1/items/search/assignments?team_id={team_id}&project_id={project_id}

Use the team_id and project_id you are looking up in the endpoint URL.

Request body:

{
    "item_id": [56301647]
}

📘
To get Team ID use one of the following python SDK functions:

SAClient.get_team_metadata(...)

SAClient.get_project_metadata(...)

To get Project ID use one of the following SDK functions:

SAClient.get_project_metadata("My Project")

SAClient.search_projects(..., return_metadata=True)

SAClient.list_projects(...)

To get item ID use one of the following SDK functions:

SAClient.list_items(project=..., name=...)

SAClient.get_item_metadata(project, item_name)

Multiple item IDs can be included in the item_id array in a single call.

Step 2 — Read the response

Returns a JSON array of all assignment events for the requested items, sorted newest first. There is no pagination — all records are returned at once.

[
  {
    "organization_id": "kjsdhfjafjkahsf",
    "team_id": 321,
    "projectId": 98,
    "itemId": 56301647,
    "assignee_email": "[email protected]",
    "assigner_email": "[email protected]",
    "date": "2026-05-09T08:12:34Z",
    "assignee_role_name": "Annotator"
  },
  {
    "organization_id": "kjsdhfjafjkahsf",
    "team_id": 321,
    "projectId": 98,
    "itemId": 56301647,
    "assignee_email": null,
    "assigner_email": "[email protected]",
    "date": "2026-05-05T08:12:34Z",
    "assignee_role_name": "Reviewer"
  }
]

📘
assignee_email is null for unassignment events. An empty array [] means no events have been logged for that item.

Response Data Reference

Field	Description
`organization_id`	ID of the organization the team belongs to.
`team_id`	ID of the team where the project was created.
`projectId`	ID of the project the item belongs to.
`itemId`	Database ID of the item that had an assignment change.
`assignee_email`	Email of the assigned user; `null` if unassigned.
`assigner_email`	Email of the user who triggered the assignment. `assignee_email` for any request tasks. Team Owner email for any SDK actions.
`date`	Timestamp of the assignment change (UTC). Results are sorted by this field in descending order.
`assignee_role_name`	Current name of the role at the time of the API call (reflects renames).