API: Datasets - TestRail

API: Datasets

Use the following API methods to upload, retrieve, update, and delete datasets.

On this page:

    get_dataset

    Retrieves the requested dataset.Parameter

    GET index.php?/api/v2/get_dataset/{dataset_id}

    Parameters

    Name Type Required Description
    dataset_id
    integer true The ID of the dataset to retrieve.

    Example request:


    # Get the dataset with an ID of 183
    GET index.php?/api/v2/get_dataset/183
    

    Response content

    {
        "id": 183,
        "name": "Default",
        "variables": [
            {
                "id": 1171,
                "name": "age",
                "value": "41"
            },
            {
                "id": 1170,
                "name": "birth_year",
                "value": "1980"
            },
            {
                "id": 1172,
                "name": "browser",
                "value": "Chrome"
            },
            {
                "id": 1169,
                "name": "name",
                "value": "Jon"
            },
            {
                "id": 1669,
                "name": "New_variable",
                "value": "m"
            }
        ]
    }
    

    Response Fields

    Name Type Description
    id
    integer The database ID of the dataset
    name
    string Name of the dataset as provided
    variables
    array Array of objects. Each object contains:
    id: The ID of the variable

    name: The name of the variable

    value: The value from the dataset corresponding to the variable

    Response codes

    Status Code Description
    200 Success
    400

    Invalid dataset_id

    Missing dataset_id

    401 Authentication Failure
    403

    Insufficient permissions (cannot access this project)

    Not an Enterprise license/subscription

    get_datasets

    Retrieves the requested list of datasets

    GET index.php?/api/v2/get_datasets/{project_id}

    Parameters

    Name Type Required Description
    project_id
    integer true The ID of the project from which to retrieve datasets

    Example request:


    # Get the dataset with an ID of 2
    GET index.php?/api/v2/get_datasets/2
    

    Response content

    {
        "offset": 0,
        "limit": 250,
        "size": 4,
        "_links": {
            "next": null,
            "prev": null
        },
        "datasets": [
            {
                "id": 183,
                "name": "Default",
                "variables": [
                    {
                        "id": 1171,
                        "name": "age",
                        "value": "41"
                    },
                    {
                        "id": 1170,
                        "name": "birth_year",
                        "value": "1980"
                    },
                    {
                        "id": 1172,
                        "name": "browser",
                        "value": "Chrome"
                    },
                    {
                        "id": 1169,
                        "name": "name",
                        "value": "Jon"
                    },
                    {
                        "id": 1669,
                        "name": "New_variable",
                        "value": "m"
                    }
                ]
            },
            {
                "id": 543,
                "name": "Dataset_name_3",
                "variables": [
                    {
                        "id": 1171,
                        "name": "age",
                        "value": "38"
                    },
                    {
                        "id": 1170,
                        "name": "birth_year",
                        "value": "1983"
                    },
                    {
                        "id": 1172,
                        "name": "browser",
                        "value": "m,,"
                    },
                    {
                        "id": 1169,
                        "name": "name",
                        "value": "Ringo"
                    },
                    {
                        "id": 1669,
                        "name": "New_variable",
                        "value": "mnm"
                    }
                ]
            },
            {
                "id": 544,
                "name": "New",
                "variables": [
                    {
                        "id": 1171,
                        "name": "age",
                        "value": "value"
                    },
                    {
                        "id": 1170,
                        "name": "birth_year",
                        "value": "n"
                    },
                    {
                        "id": 1172,
                        "name": "browser",
                        "value": "m"
                    },
                    {
                        "id": 1169,
                        "name": "name",
                        "value": "m,"
                    },
                    {
                        "id": 1669,
                        "name": "New_variable",
                        "value": "nnn"
                    }
                ]
            },
            {
                "id": 545,
                "name": "BOO",
                "variables": [
                    {
                        "id": 1171,
                        "name": "age",
                        "value": "blue"
                    },
                    {
                        "id": 1170,
                        "name": "birth_year",
                        "value": "nnb"
                    },
                    {
                        "id": 1172,
                        "name": "browser",
                        "value": "fcg"
                    },
                    {
                        "id": 1169,
                        "name": "name",
                        "value": "n,"
                    },
                    {
                        "id": 1669,
                        "name": "New_variable",
                        "value": "nbnb"
                    }
                ]
            }
        ]
    }
    

    Response Fields

    Name Type Description
    Pagination related fields
    array Fields consistent with pagination of existing bulk GET API endpoints.
    datasets
    array Array of objects, where each entry in the array is a dataset consistent with get_dataset.

    Response codes

    Status Code Description
    200 Success
    400

    Invalid project_id

    Missing project_id

    401 Authentication Failure
    403

    Insufficient permissions (cannot access this project)

    Not an Enterprise license/subscription

    add_dataset

    Creates a new dataset.

    POST index.php?/api/v2/add_dataset/{project_id}

    Parameters

    Name Type Required Description
    project_id
    integer true The ID of the project to which the dataset should be added.

    Example request:


    # Post the dataset with an ID of 12
    POST index.php?/api/v2/add_dataset/12
    

    Request Body

    {
        "id": 311,
        "name": "Def",
        "variables": []
    }
    

    Response content

    {
        "id": 648,
        "name": "Def",
        "variables": [
            {
                "id": 611,
                "name": "d",
                "value": ""
            },
            {
                "id": 612,
                "name": "e",
                "value": ""
            }
        ]
    }
    

    Response Fields

    Name Type Description
    id
    integer The database ID of the dataset
    name
    string Name of the dataset as provided.
    variable/value pairs
    array

    Key/Value pairs. Key should be the variable name. Value should be the value to be included in the dataset.

    Example: “browser”: “Chrome”

    Response codes

    Status Code Description
    200 Success
    400

    Invalid project_id

    Missing project_id

    Invalid dataset name

    Name of dataset already exists within the current project

    variable/value pairs contain invalid data (variable name does not exist, values not submitted as strings, values exceed lengths, etc.)

    Number of allowed datasets exceeded

    401 Authentication Failure
    403

    Insufficient permissions (cannot access this project)

    Not an Enterprise license/subscription

    update_dataset

    Updates an existing dataset.

    POST index.php?/api/v2/update_dataset/{dataset_id}

    Parameters

    Name Type Required Description
    dataset_id
    integer true The ID of the project to which the dataset should be updated.

    Example request:


    # Post the dataset with an ID of 2
    POST index.php?/api/v2/update_dataset/2
    

    Request Body

    The request body for the new dataset has the same response format as add_dataset.

    Response content

    If successful, this method returns the new dataset using the same response format as add_dataset.

    Response Fields

    Name Type Description
    id
    integer The database ID of the dataset
    name
    string Name of the dataset as provided.
    variable/value pairs
    array

    Key/Value pairs. Key should be the variable name. Value should be the value to be included in the dataset.

    Example: “browser”: “Chrome”

    Response codes

    Status Code Description
    200 Success
    400

    Invalid project_id

    Missing project_id

    Invalid dataset name

    Name of dataset already exists within the current project

    variable/value pairs contain invalid data (variable name does not exist, values not submitted as strings, values exceed lengths, etc.)

    Number of allowed datasets exceeded

    401 Authentication Failure
    403

    Insufficient permissions (cannot access project)

    Insufficient permissions (no add/edit permission for Test Data within the project)

    Not an Enterprise license/subscription

    delete_dataset

    Deletes an existing dataset.Parameter

    POST index.php?/api/v2/delete_dataset/{dataset_id}

    Parameters

    Name Type Required Description
    dataset_id
    integer true The ID of the dataset to be deleted.

    info Please Note: Deleting a dataset should also remove the dataset’s values.

    Response codes

    Status Code Description
    200 Success
    400

    Invalid dataset_id

    Missing dataset_id

    dataset_id is the Default dataset

    401 Authentication Failure
    403

    Insufficient permissions (cannot access project)

    Insufficient permissions (no add/edit permission for Test Data within the project)

    Not an Enterprise license/subscription