Pull Dataset

GEThttps://api.confident-ai.com/v2/datasets/{datasetId}

Retrieves the dataset with its goldens, oldest first. Pass version to pull a specific version, and finalized=false to pull the goldens still awaiting review instead of the finalized ones. Requires an active trial or paid plan, and the Team plan or above to pull a version.

GET/v2/datasets/{datasetId}

curl -X GET "https://api.confident-ai.com/v2/datasets/{datasetId}" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>"

200

{
  "success": true,
  "data": {
    "id": "<DATASET-ID>",
    "alias": "capitals",
    "multiTurn": false,
    "version": "00.00.01",
    "goldens": [
      {
        "input": "What is the capital of France?",
        "actualOutput": "The capital of France is Paris.",
        "expectedOutput": "Paris.",
        "context": [
          "Paris is the capital of France."
        ],
        "retrievalContext": [
          "Paris is the capital and largest city of France."
        ],
        "toolsCalled": [
          {
            "name": "get_landmark_info",
            "type": "FUNCTION",
            "description": "This tool gives information about a mountain.",
            "inputParameters": {
              "mountain": "Everest"
            },
            "output": "8,848 metres",
            "reasoning": "The user asked for the height of a mountain."
          }
        ],
        "expectedTools": [
          {
            "name": "get_landmark_info",
            "type": "FUNCTION",
            "description": "This tool gives information about a mountain.",
            "inputParameters": {
              "mountain": "Everest"
            },
            "output": "8,848 metres",
            "reasoning": "The user asked for the height of a mountain."
          }
        ],
        "tokenCost": 0.002,
        "inputTokenCount": 12,
        "outputTokenCount": 3,
        "id": "<GOLDEN-ID>",
        "additionalMetadata": {
          "source": "faq"
        },
        "comments": "Reviewed by the support team.",
        "sourceFile": "capitals.csv",
        "sourceFiles": [
          "capitals.csv"
        ],
        "finalized": true,
        "customColumnKeyValues": {
          "difficulty": "easy"
        },
        "tags": [
          "geography"
        ]
      }
    ]
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

datasetIdstringRequired
The unique id of the dataset.

Query parameters

versionstring
The version to pull. Defaults to the latest version, or to the unversioned goldens when the dataset has no versions. Requires the Team plan or above.
finalizedenumdefault: true
Whether to pull the finalized goldens, or with false the goldens still awaiting review. Defaults to true.

Response

Pull Dataset succeeded.

successboolean
Indicates if the request was successful.
dataobject
A pulled dataset with the goldens of one version.
Show 5 propertiesHide 5 properties
- idstring
  This is the unique id of the dataset.
- aliasstring
  This is the alias of the dataset, which is unique within your project.
- multiTurnboolean
  This is true if the dataset is multi-turn, which contains multi-turn goldens. Single-turn datasets have multiTurn set to false and contain single-turn goldens.
- versionstring | null
  The version number of the goldens returned, or null when the dataset has no versions.
- goldenslist of object | object
  The goldens in the dataset, oldest first. Every golden is single-turn or multi-turn according to the dataset's multiTurn.
  Show 2 variantsHide 2 variants
  - Single-Turn Goldenobject
    A single-turn golden as stored in the dataset.
    Show 18 propertiesHide 18 properties
    inputstring
    This is the input to your LLM application.
    actualOutputstring | null
    This is the actual output of your LLM application.
    expectedOutputstring | null
    This is the expected output of your LLM application, which is the ideal actual output.
    contextarray | null
    This is the ideal retrieval context of your LLM application.
    retrievalContextarray | null
    This is the retrieval context of your LLM application.
    toolsCalledarray | null
    This is the tools called by your LLM application.
    Show 6 propertiesHide 6 properties
    namestring
    This is the name of the tool.
    typeenum
    The type of the tool call, either a function or an MCP tool.
    Show 2 enum valuesHide 2 enum values
    FUNCTION
    MCP
    descriptionstring
    This is the description of the tool.
    inputParametersobject | null
    This is the input parameters that are passed to the tool.
    outputany
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
    expectedToolsarray | null
    This is the expected tools to be called by the LLM application.
    Show 6 propertiesHide 6 properties
    namestring
    This is the name of the tool.
    typeenum
    The type of the tool call, either a function or an MCP tool.
    Show 2 enum valuesHide 2 enum values
    FUNCTION
    MCP
    descriptionstring
    This is the description of the tool.
    inputParametersobject | null
    This is the input parameters that are passed to the tool.
    outputany
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
    tokenCostnumber | null
    This is the cost of the tokens used to produce the actual output.
    inputTokenCountinteger | null
    This is the number of input tokens passed to the LLM model.
    outputTokenCountinteger | null
    This is the number of output tokens generated by the LLM model.
    idstring
    The id of the golden assigned by Confident AI. Use it to get, update or delete this golden.
    additionalMetadataobject | null
    This is any additional metadata associated with the golden.
    commentsstring | null
    This is any comments associated with the golden.
    sourceFilestring | null
    This is the source file from which the golden was retrieved.
    sourceFileslist of strings
    These are the source files the golden was retrieved from.
    finalizedboolean
    This is true when the golden is finalized and ready to use in evaluations.
    customColumnKeyValuesobject
    Key-value pairs representing custom table column data for this golden. Keys correspond to the custom column keys defined in the dataset. Absent when the golden has no custom column values.
    tagslist of strings
    These are the tags associated with the golden.
  - OR
  - Multi-Turn Goldenobject
    A multi-turn golden as stored in the dataset.
    Show 13 propertiesHide 13 properties
    scenariostring
    This is a description of the conversation context.
    expectedOutcomestring | null
    This describes the expected outcome, or ideal conversation flow, of the conversation.
    userDescriptionstring | null
    This is the description of the user in the conversation.
    turnsarray | null
    This is the list of turns in the conversation.
    Show 6 propertiesHide 6 properties
    idstring
    The id of a turn assigned by Confident AI.
    roleenum
    The role of the turn, either user or assistant.
    Show 2 enum valuesHide 2 enum values
    user
    assistant
    contentstring
    The message content of the turn.
    userIdstring
    The user ID associated with the turn.
    retrievalContextarray | null
    The contexts retrieved to generate the LLM response for this turn.
    toolsCalledarray | null
    The tools called to generate the LLM response for this turn.
    Show 6 propertiesHide 6 properties
    namestring
    This is the name of the tool.
    typeenum
    The type of the tool call, either a function or an MCP tool.
    Show 2 enum valuesHide 2 enum values
    FUNCTION
    MCP
    descriptionstring
    This is the description of the tool.
    inputParametersobject | null
    This is the input parameters that are passed to the tool.
    outputany
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
    contextarray | null
    This is the context of the conversation.
    idstring
    The id of the golden assigned by Confident AI. Use it to get, update or delete this golden.
    additionalMetadataobject | null
    This is any additional metadata associated with the golden.
    commentsstring | null
    This is any comments associated with the golden.
    sourceFilestring | null
    This is the source file from which the golden was retrieved.
    sourceFileslist of strings
    These are the source files the golden was retrieved from.
    finalizedboolean
    This is true when the golden is finalized and ready to use in evaluations.
    customColumnKeyValuesobject
    Key-value pairs representing custom table column data for this golden. Keys correspond to the custom column keys defined in the dataset. Absent when the golden has no custom column values.
    tagslist of strings
    These are the tags associated with the golden.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI