베타 Observability 데이터셋 엔드포인트

베타 Observability 데이터셋 엔드포인트 (Beta Observability Datasets Endpoints)

(beta) Observability API - datasets입니다. 평가용 데이터셋을 만들고, 레코드를 추가·조회하며, 다양한 소스에서 가져와 데이터셋을 채우고, JSONL로 내보내는 엔드포인트예요.

출처: 문서

본문

관측성 데이터를 모아 평가에 쓸 데이터셋을 관리하는 베타 API예요. 빈 데이터셋을 만들고, 레코드를 하나씩 추가하거나 파일·플레이그라운드 대화·다른 데이터셋에서 일괄 가져오는 방법을 다룹니다. 가져오기 작업 상태도 확인할 수 있어요.

GET /v1/observability/datasets — List existing datasets (데이터셋 목록)

기존 데이터셋 목록을 가져옵니다.

쿼리 파라미터:

  • page_size#integer
  • page#integer
  • q#string|null — 검색어.

응답 필드 (200 Successful Response):

  • datasets#PaginatedResultDatasetPreview (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.list({});

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.list(page_size=50, page=1)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "datasets": {
    "count": 87
  }
}

POST /v1/observability/datasets — Create a new empty dataset (빈 데이터셋 생성)

새 빈 데이터셋을 만듭니다.

요청 본문:

  • name#string (필수) — 데이터셋 이름.
  • description#string (필수) — 데이터셋 설명.

응답 필드 (201 Successful Response):

  • id#string (필수), name#string (필수), description#string (필수), created_at#date-time, updated_at#date-time, deleted_at#date-time|null, owner_id#string (필수), workspace_id#string (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.create({
    name: "<value>",
    description: "citizen whoever sustenance necessary vibrant openly",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.create(name="<value>", description="citizen whoever sustenance necessary vibrant openly")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "description": "My Dataset description",
  "name": "My Dataset"
}'

응답 예시 (201):

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "deleted_at": null,
  "description": "My resource description.",
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "name": "My resource",
  "owner_id": "9c0ab39f-0cd0-46cd-bd30-8bf2d50be5ce",
  "updated_at": "2025-12-17T10:41:03.469341Z",
  "workspace_id": "019b2bd7-96e7-7219-8c0b-45a73da50088"
}

GET /v1/observability/datasets/{dataset_id} — Get dataset by id (데이터셋 조회)

ID로 데이터셋을 가져옵니다.

경로 파라미터:

  • dataset_id#string (필수)

응답 필드 (200 Successful Response): 생성 응답과 동일한 필드 목록.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.fetch({
    datasetId: "036fa362-e080-4fa5-beff-a334a70efb58",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.fetch(dataset_id="036fa362-e080-4fa5-beff-a334a70efb58")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id} \
 -X GET \
 -H 'Authorization: Bearer ***'

DELETE /v1/observability/datasets/{dataset_id} — Delete a dataset (데이터셋 삭제)

데이터셋을 삭제합니다.

경로 파라미터:

  • dataset_id#string (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  await mistral.beta.observability.datasets.delete({
    datasetId: "baf961a3-bb8e-4085-89ef-de9c5d8c4e77",
  });

}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    mistral.beta.observability.datasets.delete(dataset_id="baf961a3-bb8e-4085-89ef-de9c5d8c4e77")

    # Use the SDK ...

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id} \
 -X DELETE \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json'

PATCH /v1/observability/datasets/{dataset_id} — Patch dataset (데이터셋 수정)

데이터셋 이름·설명을 부분 수정합니다.

경로 파라미터:

  • dataset_id#string (필수)

요청 본문:

  • name#string|null
  • description#string|null

응답 필드 (200 Successful Response): 생성 응답과 동일한 필드 목록.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.update({
    datasetId: "95be9afc-fc05-44a6-af9f-2362de1224f9",
    updateDatasetRequest: {},
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.update(dataset_id="95be9afc-fc05-44a6-af9f-2362de1224f9")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id} \
 -X PATCH \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

GET /v1/observability/datasets/{dataset_id}/records — List existing records in the dataset (레코드 목록)

데이터셋 안의 기존 레코드를 나열합니다.

경로/쿼리 파라미터:

  • dataset_id#string (필수)
  • page_size#integer
  • page#integer

응답 필드 (200 Successful Response):

  • records#PaginatedResultDatasetRecord (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.listRecords({
    datasetId: "444d2a88-e636-4bc0-ab6c-919bedaed112",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.list_records(dataset_id="444d2a88-e636-4bc0-ab6c-919bedaed112", page_size=50, page=1)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id}/records \
 -X GET \
 -H 'Authorization: Bearer ***'

POST /v1/observability/datasets/{dataset_id}/records — Add a record to the dataset (레코드 추가)

데이터셋에 레코드를 추가합니다.

경로 파라미터:

  • dataset_id#string (필수)

요청 본문:

  • payload#map<any> (필수) — 호출자가 작성해 레코드에 저장하는 입력 객체.
  • properties#map<any>
  • source#"DIRECT_INPUT"|"TELEMETRY_SPAN" — 기본값 "DIRECT_INPUT". 레코드 생성을 시작한 채널로, 호출자가 선언한 값입니다. 이 값이 payload가 소스의 수정되지 않은 복사본임을 보증하진 않아요.

응답 필드 (201 Successful Response):

  • id#string (필수), dataset_id#string (필수), payload#map<any> (필수), properties#map<any> (필수), source#"EXPLORER"|"UPLOADED_FILE"|"DIRECT_INPUT"|"PLAYGROUND"|"TELEMETRY_SPAN" (필수), created_at#date-time, updated_at#date-time, deleted_at#date-time|null

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.createRecord({
    datasetId: "4c54ed13-1459-44e1-8696-1a6df06f7177",
    createDatasetRecordRequest: {
      payload: {
        "messages": [
          {
            "key": "<value>",
          },
          {
            "key": "<value>",
            "key1": "<value>",
          },
        ],
      },
    },
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral, models
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.create_record(dataset_id="4c54ed13-1459-44e1-8696-1a6df06f7177", payload=models.ConversationPayload(
        messages=[
            {
                "key": "<value>",
            },
            {
                "key": "<value>",
                "key1": "<value>",
            },
        ],
    ), properties={
        "key": "<value>",
        "key1": "<value>",
        "key2": "<value>",
    })

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id}/records \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "payload": [
    null
  ]
}'

POST /v1/observability/datasets/{dataset_id}/imports/from-file — Populate the dataset with records from an uploaded file (파일로 데이터셋 채우기)

업로드한 파일의 레코드로 데이터셋을 채웁니다.

경로/요청 파라미터:

  • dataset_id#string (필수)
  • file_id#string (필수) — 업로드된 파일의 ID.

응답 필드 (202 Successful Response):

  • id#string (필수), dataset_id#string (필수), creator_id#string (필수), workspace_id#string (필수), status#"RUNNING"|"COMPLETED"|"FAILED"|"CANCELED"|"TERMINATED"|"CONTINUED_AS_NEW"|"TIMED_OUT"|"UNKNOWN" (필수), created_at#date-time, updated_at#date-time, deleted_at#date-time|null, message#string|null, progress#integer|null

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.importFromFile({
    datasetId: "1c96c925-cc58-4529-863d-9fe66a6f1924",
    importDatasetFromFileRequest: {
      fileId: "<id>",
    },
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.import_from_file(dataset_id="1c96c925-cc58-4529-863d-9fe66a6f1924", file_id="<id>")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id}/imports/from-file \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "file_id": "7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f"
}'

POST /v1/observability/datasets/{dataset_id}/imports/from-playground — Import from playground (플레이그라운드 대화로 채우기)

플레이그라운드 대화의 레코드로 데이터셋을 채웁니다.

경로/요청 파라미터:

  • dataset_id#string (필수)
  • conversation_ids#array<string> (필수) — 가져올 대화 ID 목록.

응답 필드 (202 Successful Response): from-file과 동일한 작업 응답 필드.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.importFromPlayground({
    datasetId: "5cb42584-5fcf-4837-997a-6a67c5e6900d",
    importDatasetFromPlaygroundRequest: {
      conversationIds: [],
    },
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.import_from_playground(dataset_id="5cb42584-5fcf-4837-997a-6a67c5e6900d", conversation_ids=[])

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id}/imports/from-playground \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "conversation_ids": [
    "9d8c7b6a-5e4f-3210-fedc-ba9876543210"
  ]
}'

POST /v1/observability/datasets/{dataset_id}/imports/from-dataset — Import from another dataset (다른 데이터셋에서 가져오기)

다른 데이터셋의 레코드들로 데이터셋을 채웁니다.

경로/요청 파라미터:

  • dataset_id#string (필수)
  • dataset_record_ids#array<string> (필수) — 가져올 레코드 ID 목록.

응답 필드 (202 Successful Response): 작업 응답 필드와 동일.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.importFromDatasetRecords({
    datasetId: "ada96a08-d724-4e5c-9111-aaf1bdb7d588",
    importDatasetFromDatasetRequest: {
      datasetRecordIds: [
        "58fe798a-537b-4c61-9efc-d1d96d5d264a",
        "cfa1d197-deda-456e-906b-dd84dccfcd17",
      ],
    },
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.import_from_dataset_records(dataset_id="ada96a08-d724-4e5c-9111-aaf1bdb7d588", dataset_record_ids=[
        "58fe798a-537b-4c61-9efc-d1d96d5d264a",
        "cfa1d197-deda-456e-906b-dd84dccfcd17",
    ])

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id}/imports/from-dataset \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "dataset_record_ids": [
    "c2e8a4f0-1d3b-4a6c-8e9f-0a1b2c3d4e5f"
  ]
}'

GET /v1/observability/datasets/{dataset_id}/exports/to-jsonl — Export to JSONL (JSONL 내보내기)

파일로 내보내기 위해 Files API로 데이터를 내보내고, 결과 JSONL 파일을 내려받을 사전 서명된 URL을 받습니다.

경로 파라미터:

  • dataset_id#string (필수)

응답 필드 (200 Successful Response):

  • file_url#string (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.exportToJsonl({
    datasetId: "d521add6-d909-4a69-a460-cb880d87b773",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.export_to_jsonl(dataset_id="d521add6-d909-4a69-a460-cb880d87b773")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id}/exports/to-jsonl \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "file_url": "https://example.com/data.jsonl"
}

GET /v1/observability/datasets/{dataset_id}/tasks/{task_id} — Get status of a dataset import task (가져오기 작업 상태 조회)

데이터셋 가져오기 작업의 상태를 가져옵니다.

경로 파라미터:

  • dataset_id#string (필수)
  • task_id#string (필수)

응답 필드 (200 Successful Response): id, dataset_id, creator_id, workspace_id, status, created_at, updated_at, deleted_at, message, progress (가져오기 작업 필드와 동일).

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.fetchTask({
    datasetId: "b64b504e-58a2-4d52-979b-e2634b301235",
    taskId: "1713cde2-dea1-410d-851e-8cea964ffa14",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.fetch_task(dataset_id="b64b504e-58a2-4d52-979b-e2634b301235", task_id="1713cde2-dea1-410d-851e-8cea964ffa14")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id}/tasks/{task_id} \
 -X GET \
 -H 'Authorization: Bearer ***'

GET /v1/observability/datasets/{dataset_id}/tasks — List import tasks for the given dataset (가져오기 작업 목록)

주어진 데이터셋의 가져오기 작업 목록을 가져옵니다.

경로/쿼리 파라미터:

  • dataset_id#string (필수)
  • page_size#integer
  • page#integer

응답 필드 (200 Successful Response):

  • tasks#PaginatedResultDatasetImportTask (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.observability.datasets.listTasks({
    datasetId: "29903443-7f9c-42a6-9b6b-fc5cbef4191a",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.observability.datasets.list_tasks(dataset_id="29903443-7f9c-42a6-9b6b-fc5cbef4191a", page_size=50, page=1)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/observability/datasets/{dataset_id}/tasks \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "tasks": {
    "count": 87
  }
}

더 알아보기 (Learn more)