Dataset APIs - Akhara

Overview

Datasets are collections of samples that you evaluate. Each dataset belongs to a project and contains samples of a specific modality (voice, notes, or imaging). Base URL: https://api.akhara.ai/v1/datasets

Create Dataset

Create a new dataset within a project.

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Human-readable name for the dataset
`project`	string	Yes	Project ID (`proj_xxx`)
`description`	string	No	Description of the dataset contents
`modality`	string	Yes	One of: `voice`, `notes`, `imaging`
`schema`	object	No	Custom schema for sample validation
`metadata`	object	No	Arbitrary key-value pairs

Example Request

from akhara import Akhara

client = Akhara()

dataset = client.datasets.create(
    name="Q1 Triage Calls",
    project="proj_abc123",
    description="Production triage calls from Q1 2024",
    modality="voice",
    metadata={
        "source": "production",
        "date_range": "2024-01-01 to 2024-03-31"
    }
)

print(f"Created dataset: {dataset.id}")

import Akhara from '@akhara/sdk';

const client = new Akhara();

const dataset = await client.datasets.create({
  name: "Q1 Triage Calls",
  project: "proj_abc123",
  description: "Production triage calls from Q1 2024",
  modality: "voice",
  metadata: {
    source: "production",
    date_range: "2024-01-01 to 2024-03-31"
  }
});

console.log(`Created dataset: ${dataset.id}`);

curl -X POST https://api.akhara.ai/v1/datasets \
  -H "Authorization: Bearer rb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Triage Calls",
    "project": "proj_abc123",
    "description": "Production triage calls from Q1 2024",
    "modality": "voice",
    "metadata": {
      "source": "production",
      "date_range": "2024-01-01 to 2024-03-31"
    }
  }'

Response

{
  "id": "ds_xyz789",
  "object": "dataset",
  "name": "Q1 Triage Calls",
  "project": "proj_abc123",
  "description": "Production triage calls from Q1 2024",
  "modality": "voice",
  "sample_count": 0,
  "schema": null,
  "metadata": {
    "source": "production",
    "date_range": "2024-01-01 to 2024-03-31"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List Datasets

Retrieve all datasets in a project or organization.

Query Parameters

Parameter	Type	Required	Description
`project`	string	No	Filter by project ID
`modality`	string	No	Filter by modality
`limit`	integer	No	Results per page (1-100, default 20)
`after`	string	No	Cursor for pagination

Example Request

# List all datasets in a project
datasets = client.datasets.list(
    project="proj_abc123",
    limit=50
)

for ds in datasets:
    print(f"{ds.name}: {ds.sample_count} samples")

# Paginate through results
all_datasets = []
cursor = None
while True:
    page = client.datasets.list(project="proj_abc123", after=cursor)
    all_datasets.extend(page.data)
    if not page.has_more:
        break
    cursor = page.data[-1].id

curl "https://api.akhara.ai/v1/datasets?project=proj_abc123&limit=50" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

Response

{
  "object": "list",
  "data": [
    {
      "id": "ds_xyz789",
      "object": "dataset",
      "name": "Q1 Triage Calls",
      "project": "proj_abc123",
      "modality": "voice",
      "sample_count": 1247,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ds_abc456",
      "object": "dataset",
      "name": "Golden Test Set",
      "project": "proj_abc123",
      "modality": "voice",
      "sample_count": 200,
      "created_at": "2024-01-10T08:00:00Z"
    }
  ],
  "has_more": false
}

Get Dataset

Retrieve a specific dataset by ID.

Path Parameters

Parameter	Type	Required	Description
`dataset_id`	string	Yes	The dataset ID

Example Request

dataset = client.datasets.get("ds_xyz789")

print(f"Name: {dataset.name}")
print(f"Samples: {dataset.sample_count}")
print(f"Modality: {dataset.modality}")

curl "https://api.akhara.ai/v1/datasets/ds_xyz789" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

Update Dataset

Update dataset metadata or configuration.

Request Body

Parameter	Type	Required	Description
`name`	string	No	Updated name
`description`	string	No	Updated description
`metadata`	object	No	Updated metadata (merged with existing)

Example Request

dataset = client.datasets.update(
    "ds_xyz789",
    name="Q1 2024 Triage Calls (Final)",
    metadata={"status": "reviewed", "reviewer": "dr.smith"}
)

curl -X PATCH "https://api.akhara.ai/v1/datasets/ds_xyz789" \
  -H "Authorization: Bearer rb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 2024 Triage Calls (Final)",
    "metadata": {"status": "reviewed"}
  }'

Delete Dataset

Delete a dataset and all its samples.

This permanently deletes the dataset and all samples. This action cannot be undone.

Example Request

client.datasets.delete("ds_xyz789")

curl -X DELETE "https://api.akhara.ai/v1/datasets/ds_xyz789" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

Response

{
  "id": "ds_xyz789",
  "object": "dataset",
  "deleted": true
}

Add Samples

Add samples to a dataset. Supports single or batch upload.

Request Body

Parameter	Type	Required	Description
`samples`	array	Yes	Array of sample objects

Sample Object (Voice)

Field	Type	Required	Description
`input.transcript`	array	Yes	Transcript with speaker turns
`input.audio_url`	string	No	URL to audio file
`output`	object	Yes	AI system output to evaluate
`expected`	object	No	Ground truth for comparison
`metadata`	object	No	Additional context

Example Request

# Add single sample
sample = client.datasets.add_sample(
    dataset="ds_xyz789",
    input={
        "transcript": [
            {"speaker": "agent", "text": "How can I help you today?", "start": 0.0, "end": 2.1},
            {"speaker": "patient", "text": "I have chest pain.", "start": 2.5, "end": 4.2}
        ],
        "audio_url": "s3://bucket/calls/call_123.wav"
    },
    output={
        "triage_level": "urgent",
        "symptoms": ["chest_pain"],
        "recommended_action": "immediate_callback"
    },
    expected={
        "triage_level": "emergent"
    },
    metadata={
        "call_id": "call_123",
        "duration_seconds": 85
    }
)

# Batch upload
samples = client.datasets.add_samples(
    dataset="ds_xyz789",
    samples=[
        {"input": {...}, "output": {...}},
        {"input": {...}, "output": {...}},
        # ... up to 100 samples per batch
    ]
)

curl -X POST "https://api.akhara.ai/v1/datasets/ds_xyz789/samples" \
  -H "Authorization: Bearer rb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "samples": [
      {
        "input": {
          "transcript": [
            {"speaker": "agent", "text": "How can I help?", "start": 0.0, "end": 1.5}
          ]
        },
        "output": {
          "triage_level": "urgent"
        }
      }
    ]
  }'

Response

{
  "object": "list",
  "data": [
    {
      "id": "smp_abc123",
      "object": "sample",
      "dataset": "ds_xyz789",
      "created_at": "2024-01-15T10:35:00Z"
    }
  ],
  "successful": 1,
  "failed": 0
}

List Samples

List samples in a dataset with optional filtering.

Query Parameters

Parameter	Type	Description
`limit`	integer	Results per page (1-100)
`after`	string	Pagination cursor
`has_expected`	boolean	Filter to samples with ground truth
`metadata`	object	Filter by metadata fields

Example Request

# List samples with ground truth
samples = client.datasets.list_samples(
    dataset="ds_xyz789",
    has_expected=True,
    limit=50
)

for sample in samples:
    print(f"{sample.id}: {sample.output.get('triage_level')}")

curl "https://api.akhara.ai/v1/datasets/ds_xyz789/samples?has_expected=true&limit=50" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

Get Sample

Retrieve a specific sample by ID.

Example Request

sample = client.datasets.get_sample(
    dataset="ds_xyz789",
    sample="smp_abc123"
)

print(sample.input)
print(sample.output)
print(sample.expected)

curl "https://api.akhara.ai/v1/datasets/ds_xyz789/samples/smp_abc123" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

Export Dataset

Export a dataset to various formats.

Request Body

Parameter	Type	Required	Description
`format`	string	Yes	`json`, `jsonl`, `csv`, `parquet`
`include_phi`	boolean	No	Include PHI fields (requires permission)
`filters`	object	No	Filter samples to export

Example Request

export = client.datasets.export(
    dataset="ds_xyz789",
    format="jsonl",
    include_phi=False
)

# Download when ready
export.wait()
export.download("q1_triage_calls.jsonl")

curl -X POST "https://api.akhara.ai/v1/datasets/ds_xyz789/export" \
  -H "Authorization: Bearer rb_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"format": "jsonl", "include_phi": false}'

Response

{
  "id": "exp_xyz123",
  "object": "export",
  "status": "processing",
  "format": "jsonl",
  "dataset": "ds_xyz789",
  "sample_count": 1247,
  "download_url": null,
  "expires_at": null,
  "created_at": "2024-01-15T11:00:00Z"
}

Evaluation APIs

Run evaluations on your datasets

Sample Schemas

Schema definitions for each modality

​Overview

​Create Dataset

​Request Body

​Example Request

​Response

​List Datasets

​Query Parameters

​Example Request

​Response

​Get Dataset

​Path Parameters

​Example Request

​Update Dataset

​Request Body

​Example Request

​Delete Dataset

​Example Request

​Response

​Add Samples

​Request Body

​Sample Object (Voice)

​Example Request

​Response

​List Samples

​Query Parameters

​Example Request

​Get Sample

​Example Request

​Export Dataset

​Request Body

​Example Request

​Response

​Related

Evaluation APIs

Sample Schemas

Overview

Create Dataset

Request Body

Example Request

Response

List Datasets

Query Parameters

Example Request

Response

Get Dataset

Path Parameters

Example Request

Update Dataset

Request Body

Example Request

Delete Dataset

Example Request

Response

Add Samples

Request Body

Sample Object (Voice)

Example Request

Response

List Samples

Query Parameters

Example Request

Get Sample

Example Request

Export Dataset

Request Body

Example Request

Response

Related