Datasets API

The Datasets API enables your organization to browse, review, and manage training datasets from the Gerra platform.

Base URL

https://api.gerra.com

Authentication

All dataset endpoints require authentication using an API key in the Gerra-Api-Key header. You can find your API key in your dashboard.

curl "https://api.gerra.com/datasets" \
  -H "Gerra-Api-Key: YOUR_API_KEY"

Endpoints Overview

Method	Endpoint	Description
`GET`	`/datasets`	List all datasets with filtering
`GET`	`/datasets/dataset`	Get a single dataset with download URL
`GET`	`/datasets/stats`	Get dataset statistics
`GET`	`/datasets/{id}/iterations`	Get iteration history
`POST`	`/datasets/{id}/accept`	Accept a pending dataset
`POST`	`/datasets/{id}/reject`	Reject a pending dataset

Dataset Object

All dataset responses include the following fields:

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "date_created": "2025-01-15T10:30:00Z",
  "date_updated": "2025-01-15T14:45:00Z",
  "organization_id": "660e8400-e29b-41d4-a716-446655440000",
  "data_type": "episode",
  "name": "Robot Arm Sensor Data Q1 2025",
  "description": "Telemetry data from robot arm sensors",
  "status": "pending",
  "link": "datasets/robot-arm-q1-2025.zip",
  "signed_url": "https://storage.example.com/...",
  "data_byte_size": 257355776,
  "metadata": {
    "sensor_type": "thermal",
    "location": "factory_floor_3"
  }
}

Dataset Fields

Field	Type	Description
`id`	string	Unique dataset identifier (UUID)
`date_created`	string	ISO 8601 creation timestamp
`date_updated`	string	ISO 8601 last update timestamp
`organization_id`	string	Owning organization ID
`data_type`	string	Type of data (episode, synthetic_pov, synthetic_third_person, telemetry)
`name`	string	Dataset name
`description`	string	Optional description
`status`	string	Current status
`link`	string	Storage path
`signed_url`	string	Pre-signed download URL (60 min expiry)
`data_byte_size`	integer	Size in bytes
`metadata`	object	Custom metadata key-value pairs

Dataset Status

Datasets flow through the following states:

Status	Description
`pending`	Awaiting review by your organization
`accepted`	Approved and ready for training pipelines
`rejected`	Rejected with reason stored in metadata

Data Types

Type	Description
`episode`	Real robot deployment recordings
`synthetic_pov`	AI-generated first-person perspective video
`synthetic_third_person`	AI-generated third-person perspective video
`telemetry`	Sensor and telemetry data streams

Pagination

List endpoints support pagination with limit and offset parameters:

# Get page 2 with 50 items per page
curl "https://api.gerra.com/datasets?limit=50&offset=50" \
  -H "Gerra-Api-Key: gerra_your_api_key"

Parameter	Type	Default	Max	Description
`limit`	integer	100	1000	Number of results to return
`offset`	integer	0	-	Number of results to skip

Error Handling

The API uses standard HTTP status codes:

Code	Description
`200`	Success
`400`	Bad request (invalid parameters)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (dataset belongs to another organization)
`404`	Not found
`422`	Validation error
`500`	Internal server error

Error responses include a detail field:

{
  "detail": "Missing Gerra-Api-Key header"
}

Datasets API Overview