Skip to main content

List Datasets

Retrieve a paginated list of datasets with optional filtering.

Endpoint​

GET https://api.platform.knowledgator.com/datasets/


Headers​

NameTypeDescription
KnowledgatorAPI-KeyStringYour API key
Content-TypeStringapplication/json

Request Parameters​

ParameterTypeRequiredDescription
offsetIntegerNoPagination offset (default: 0, min: 0).
limitIntegerNoMaximum results per page (default: 100, max: 10000).
nameStringNoFilter by dataset name (regex ^[a-zA-Z0-9- .()]+$).
typeStringNoFilter by service type: comprehend-it, extract-it, instruct-it.
formatStringNoFilter by dataset format (json).
statusStringNoFilter by status: pending, valid, invalid.

Response​

{
"total": 1,
"data": [
{
"id": "d655eda9-ca67-4a86-a8bc-5b3911233c79",
"name": "test-gen-dataset",
"type": "comprehend-it",
"format": "json",
"short_description": "Product review sentiment classification",
"created_by": "a1b2c3d4e5f67890123456789abcdef0",
"created_at": "2026-09-16T10:45:51Z",
"updated_at": "2026-09-16T10:45:51Z",
"examples_count": 1,
"status": "valid",
"source": "generated",
"files": [
{
"id": "f11e0000b8c7415ebc1b8071ea6ac60a",
"size": 559,
"created_by": "a1b2c3d4e5f67890123456789abcdef0",
"created_at": "2026-09-16T10:45:53Z",
"updated_at": "2026-09-16T10:45:53Z",
"application_id": null
}
],
"generation_status": {
"id": "d655eda9-ca67-4a86-a8bc-5b3911233c79",
"status": "succeeded",
"created_at": "2026-09-16T10:45:51.295073+00:00",
"updated_at": "2026-09-16T10:45:54.264276+00:00"
}
}
]
}

Response Fields​

  • total: Total number of datasets matching the filter criteria.
  • data: Array of dataset objects:
    • id: Unique dataset identifier (UUID).
    • name: Dataset name.
    • type: Service task type (comprehend-it, extract-it, instruct-it).
    • format: Dataset format (json).
    • short_description: Optional dataset description (or null).
    • created_by: Creator user identifier (UUID).
    • created_at: ISO 8601 creation timestamp.
    • updated_at: ISO 8601 last update timestamp.
    • examples_count: Number of data examples contained in the dataset.
    • status: Dataset status (valid, invalid, pending).
    • source: Dataset origin:
      • "uploaded": Directly uploaded user dataset.
      • "generated": Synthetically generated from scratch or annotated from raw data.
      • "annotated": Pre-existing raw data that was automatically annotated.
    • files: List of attached file records with id, size, created_by, created_at, updated_at, and application_id.
    • generation_status: Pipeline status object (or null when source is "uploaded"):
      • id: Unique task identifier (UUID matching dataset ID).
      • status: Current pipeline state: "running", "succeeded", or "failed".
      • created_at: Timestamp when generation was initiated.
      • updated_at: Timestamp of the latest status transition.

💡 SDK Note: The Knowledgator REST API returns the list under the "data" field. The official Python and TypeScript SDKs alias "data" to .datasets for convenience.


Error Codes​

Status CodeDescription
200OK – Request successful.
400Bad Request – Invalid parameter values.
401Unauthorized – Invalid or missing API key.
500Internal Server Error – Server-side issue.

Example Usage​

SDK Usage​

💡 Dedicated SDK Guides: See Python SDK | TypeScript SDK

TypeScript / JavaScript​

import { createClient } from '@knowledgator/typescript-sdk';

const kg = createClient('YOUR_API_KEY');

// List datasets
const result = await kg.datasets.list({
limit: 20,
type: "comprehend-it"
});

console.log(`Total: ${result.total}`);
result.datasets.forEach(ds => console.log(ds.id, ds.name));

Python SDK​

from knowledgator import Knowledgator

kg = Knowledgator(api_key="YOUR_API_KEY")

result = kg.datasets.list(
limit=20,
type="comprehend-it"
)

print(f"Total: {result.total}")
for ds in result.datasets:
print(ds.id, ds.name, ds.status)

Expected SDK Output​

Total: 1
6babd48a-2256-4466-b16b-9fd45ba59688 Ecomm Categories v1.1 valid

Python (Requests)​

import requests

url = "https://api.platform.knowledgator.com/datasets/"
headers = {
"KnowledgatorAPI-Key": "YOUR_API_KEY"
}

params = {
"type": "comprehend-it",
"limit": 20
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Expected Response (Python Requests)​

{
"total": 1,
"data": [
{
"id": "d655eda9-ca67-4a86-a8bc-5b3911233c79",
"name": "test-gen-dataset",
"type": "comprehend-it",
"format": "json",
"short_description": "Product review sentiment classification",
"created_by": "a1b2c3d4e5f67890123456789abcdef0",
"created_at": "2026-09-16T10:45:51Z",
"updated_at": "2026-09-16T10:45:51Z",
"examples_count": 1,
"status": "valid",
"source": "generated",
"files": [
{
"id": "f11e0000b8c7415ebc1b8071ea6ac60a",
"size": 559,
"created_by": "a1b2c3d4e5f67890123456789abcdef0",
"created_at": "2026-09-16T10:45:53Z",
"updated_at": "2026-09-16T10:45:53Z",
"application_id": null
}
],
"generation_status": {
"id": "d655eda9-ca67-4a86-a8bc-5b3911233c79",
"status": "succeeded",
"created_at": "2026-09-16T10:45:51.295073+00:00",
"updated_at": "2026-09-16T10:45:54.264276+00:00"
}
}
]
}

cURL​

curl -X GET "https://api.platform.knowledgator.com/datasets/?type=comprehend-it&limit=20" \
-H "KnowledgatorAPI-Key: YOUR_API_KEY"

Expected Response (cURL)​

{
"total": 1,
"data": [
{
"id": "d655eda9-ca67-4a86-a8bc-5b3911233c79",
"name": "test-gen-dataset",
"type": "comprehend-it",
"format": "json",
"short_description": "Product review sentiment classification",
"created_by": "a1b2c3d4e5f67890123456789abcdef0",
"created_at": "2026-09-16T10:45:51Z",
"updated_at": "2026-09-16T10:45:51Z",
"examples_count": 1,
"status": "valid",
"source": "generated",
"files": [
{
"id": "f11e0000b8c7415ebc1b8071ea6ac60a",
"size": 559,
"created_by": "a1b2c3d4e5f67890123456789abcdef0",
"created_at": "2026-09-16T10:45:53Z",
"updated_at": "2026-09-16T10:45:53Z",
"application_id": null
}
],
"generation_status": {
"id": "d655eda9-ca67-4a86-a8bc-5b3911233c79",
"status": "succeeded",
"created_at": "2026-09-16T10:45:51.295073+00:00",
"updated_at": "2026-09-16T10:45:54.264276+00:00"
}
}
]
}