Get a dataset by key – GET /v1/datasets

GET/v1/datasets

betaapiKeyworkspace

When to use

Resolve the dataset associated with an exact caller-owned stable key.

For agents

Use this on later runs when the caller retained the key instead of the Permute dataset ID.

Example

typescript

import { PermuteClient } from '@permute/sdk';

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const client = orgClient.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const result = await client.datasets.getByKey('quickbooks');

Response

json

{
  "data": {
    "type": "custom",
    "id": "data_quickbooks123",
    "sourceId": "data_quickbooks123",
    "key": "quickbooks",
    "name": "QuickBooks",
    "context": [
      "quickbooks"
    ],
    "status": "completed",
    "version": 3,
    "tables": [
      {
        "name": "orders",
        "rowCount": 250,
        "columnCount": 3
      },
      {
        "name": "customers",
        "rowCount": 80,
        "columnCount": 2
      }
    ],
    "createdAt": "2026-06-27T12:00:00.000Z",
    "updatedAt": "2026-06-27T12:05:00.000Z"
  }
}