Skip to main content

​
Sessions API

Access session data, logs, and artifacts from your devices.

​
Sessions

​
List Sessions

GET /organizations/{org}/projects/{project}/sessions
Query Parameters:
ParameterTypeDescription
device_idintegerFilter by device
statusstringFilter: active, completed, failed
sincedatetimeSessions after this time (ISO 8601)
untildatetimeSessions before this time
pageintegerPage number
page_sizeintegerItems per page
Response: 
{
  "items": [
    {
      "id": 456,
      "device_id": 123,
      "device_name": "warehouse-robot-01",
      "status": "completed",
      "started_at": "2025-01-10T08:00:00Z",
      "ended_at": "2025-01-10T10:30:00Z",
      "duration_seconds": 9000,
      "tags": ["production", "shift-1"],
      "artifact_count": 15
    }
  ],
  "total": 100,
  "page": 1
}

​
Get Session

GET /organizations/{org}/projects/{project}/sessions/{session_id}
Response: 
{
  "id": 456,
  "device_id": 123,
  "device_name": "warehouse-robot-01",
  "status": "completed",
  "started_at": "2025-01-10T08:00:00Z",
  "ended_at": "2025-01-10T10:30:00Z",
  "duration_seconds": 9000,
  "tags": ["production"],
  "metrics": {
    "log_count": 15432,
    "artifact_count": 15,
    "artifact_size_bytes": 1048576
  },
  "package": {
    "id": 10,
    "name": "perception-v2.1.0"
  }
}

​
Delete Session

DELETE /organizations/{org}/projects/{project}/sessions/{session_id}
This permanently deletes the session and all associated logs and artifacts.

​
Add Tag to Session

POST /organizations/{org}/projects/{project}/sessions/{session_id}/tags
Request Body: 
{
  "tag": "important"
}

​
Remove Tag from Session

DELETE /organizations/{org}/projects/{project}/sessions/{session_id}/tags/{tag}

​
Logs

​
Get Session Logs

GET /organizations/{org}/projects/{project}/sessions/{session_id}/logs
Query Parameters:
ParameterTypeDescription
levelstringFilter: debug, info, warn, error
modulestringFilter by module name
searchstringText search in messages
sincedatetimeLogs after this time
untildatetimeLogs before this time
limitintegerMax logs to return (default: 100)
Response: 
{
  "items": [
    {
      "timestamp": "2025-01-10T10:23:45.123Z",
      "level": "INFO",
      "module": "perception",
      "message": "Detected 5 obstacles",
      "metadata": {
        "obstacle_count": 5
      }
    }
  ],
  "total": 15432
}

​
Stream Logs (WebSocket)

wss://api.roboticks.io/ws/organizations/{org}/projects/{project}/sessions/{session_id}/logs
Connect via WebSocket to receive real-time logs for active sessions.

​
Export Logs

GET /organizations/{org}/projects/{project}/sessions/{session_id}/logs/export
Query Parameters:
ParameterTypeDescription
formatstringjson or csv
Returns a downloadable file.

​
Artifacts

​
List Session Artifacts

GET /organizations/{org}/projects/{project}/sessions/{session_id}/files
Response: 
{
  "items": [
    {
      "path": "logs/session.log",
      "size_bytes": 102400,
      "content_type": "text/plain",
      "created_at": "2025-01-10T10:30:00Z"
    },
    {
      "path": "data/telemetry.json",
      "size_bytes": 51200,
      "content_type": "application/json"
    },
    {
      "path": "screenshots/final.png",
      "size_bytes": 204800,
      "content_type": "image/png"
    }
  ]
}

​
Download Artifact

GET /organizations/{org}/projects/{project}/sessions/{session_id}/files/{path}
Returns the file content with appropriate Content-Type header.

​
Download All Artifacts

GET /organizations/{org}/projects/{project}/sessions/{session_id}/files/download
Returns a ZIP archive of all session artifacts.

​
Code Examples

import requests

API_KEY = "rbtk_xxx"
BASE = "https://api.roboticks.io/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}

# List completed sessions
sessions = requests.get(
    f"{BASE}/organizations/acme/projects/warehouse/sessions",
    headers=headers,
    params={"status": "completed", "since": "2025-01-01T00:00:00Z"}
).json()["items"]

# Get logs for a session
logs = requests.get(
    f"{BASE}/organizations/acme/projects/warehouse/sessions/456/logs",
    headers=headers,
    params={"level": "error", "limit": 50}
).json()["items"]

# Download artifact
response = requests.get(
    f"{BASE}/organizations/acme/projects/warehouse/sessions/456/files/logs/session.log",
    headers=headers
)
with open("session.log", "wb") as f:
    f.write(response.content)