Documentation

DataSet API

DataSet API Reference

The DataSet objects allows you to create, import, export and manage DataSets and manage data permissions for DataSets within Domo.

Best practices
The DataSet API should be used to create and update small DataSets that occasionally need their data updated. For creating and updating massive, constantly changing, or rapidly growing DataSets, the Stream API is recommended.

The DataSet object

Attributes

Property Name Type Description
id String ID of the DataSet
name String Name of the DataSet
description String Description of DataSet
owner.id String ID of the owner
owner.name String Name of the owner
columns Number The number of columns currently in the DataSet
createdAt String An ISO-8601 representation of the creation date of the DataSet
updatedAt String AN ISO-8601 representation of the time the DataSet was last updated
dataCurrentAt String An ISO-8601 representation of the time the DataSet was current
schema Object The current schema associated with this DataSet
schema.columns Array Array of columns in the DataSet
schema.columns[].name String Column name in the DataSet schema
schema.columns[].type String Column type in the DataSet schema. Valid types are STRING, DECIMAL, LONG, DOUBLE, DATE, DATETIME.
pdpEnabled Boolean Indicates if PDP [Personalized Data Permission] policy filtering on data is active on this DataSet
policies Array List of policies attached to DataSet
policies[].filters[].column String Name of the column to filter on
policies[].filters[].not Boolean Determines if NOT is applied to the filter operation
policies[].filters[].operator String Matching operator (EQUALS)
policies[].filters[].values[] String Values to filter on
policies[].groups Array List of group IDs the policy applies to
policies[].id Number ID of the Policy
policies[].name String Name of the Policy
policies[].type String Type of policy (user or system)
policies[].users Array List of user IDs the policy applies to
rows Number The number of rows currently in the DataSet

Retrieve a DataSet

Retrieves the details of an existing DataSet.

Definition

https://api.domo.com/v1/datasets/{DATASET_ID}

Arguments

Property Name Type Required Description
dataset_id string Required The ID of the DataSet

Sample Request

See it in your language

See this sample request in Java and Python.
GET https://api.domo.com/v1/datasets/08a061e2-12a2-4646-b4bc-20beddb403e3
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

Returns

Returns a DataSet object if valid DataSet ID was provided. When requesting, if the DataSet ID is related to a DataSet that has been deleted, a subset of the DataSet's information will be returned, including a deleted property, which will be true.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "08a061e2-12a2-4646-b4bc-20beddb403e3",
  "name": "Timeline Feed",
  "description": "Important",
  "rows": 1,
  "columns": 6,
  "schema": {
    "columns": [ {
      "type": "STRING",
      "name": "Name"
    } ]
  },
  "createdAt": "2015-12-10T07:06:14Z",
  "updatedAt": "2016-02-29T20:56:20.567Z",
  "pdpEnabled": false,
  "policies": [ {
    "id": 8,
    "type": "user",
    "name": "Only Show Attendees",
    "filters": [ {
      "column": "Attending",
      "values": [ "TRUE" ],
      "operator": "EQUALS",
      "not": false
    } ],
    "users": [ 27 ],
    "groups": [ ]
  } ]
}

Create a DataSet

Creates a new DataSet in your Domo instance. Once the DataSet has been created, data can then be imported into the DataSet.

Definition

POST https://api.domo.com/v1/datasets

Arguments

Property Name Type Required Description
name String Required Name of the DataSet to create
description String Required Description of DataSet to create
schema Object Required The current schema associated with this DataSet
schema.columns Array Required Array of columns in the DataSet
schema.columns[].name String Required Column name in the DataSet schema
schema.columns[].type String Required Column type in the DataSet schema. Valid types are STRING, DECIMAL, LONG, DOUBLE, DATE, and DATETIME.

Sample Request

See it in your language

See this sample request in Java and Python.
POST https://api.domo.com/v1/datasets
Content-Type: application/json
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

{
  "name": "Leonhard Euler Party",
  "description": "Mathematician Guest List",
  "rows": 0,
  "schema": {
    "columns": [ {
      "type": "STRING",
      "name": "Friend"
    }, {
      "type": "STRING",
      "name": "Attending"
    } ]
  }
}

Returns

Returns a DataSet object when successful. The returned object will have DataSet attributes based on the information that was provided when DataSet was created.

Sample Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "4405ff58-1957-45f0-82bd-914d989a3ea3",
  "name": "Leonhard Euler Party",
  "description": "Mathematician Guest List",
  "rows": 0,
  "columns": 0,
  "schema": {
    "columns": [ {
      "type": "STRING",
      "name": "Friend"
    }, {
      "type": "STRING",
      "name": "Attending"
    } ]
  },
  "owner": {
    "id": 27,
    "name": "DomoSupport"
  },
  "createdAt": "2016-06-21T17:20:36Z",
  "updatedAt": "2016-06-21T17:20:36Z"
}

Update a DataSet

Updates the specified DataSet’s metadata by providing values to parameters passed.

Definition

PUT https://api.domo.com/v1/datasets/{DATASET_ID}

Arguments

Property Name Type Required Description
dataset_id string Required The ID of the DataSet
name String - Name of the DataSet to create
description String - Description of DataSet to create
schema Object - The current schema associated with this DataSet
schema.columns Array - Array of columns in the DataSet
schema.columns[].name String - Column name in the DataSet schema
schema.columns[].type String - Column type in the DataSet schema. Valid types are STRING, DECIMAL, LONG, DOUBLE, DATE, and DATETIME.

Sample Request

See it in your language

See this sample request in Java and Python.
PUT https://api.domo.com/v1/datasets/317970a1-6a6e-4f70-8e09-44cf5f34cf44
Content-Type: application/json
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

{
  "name": "Leonhard Euler Birthday Bash",
  "description": "VIP Guest List",
  "pdpEnabled": true
}

Returns

Returns a full DataSet object.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 908

{
  "id": "4405ff58-1957-45f0-82bd-914d989a3ea3",
  "name": "Leonhard Euler Birthday Bash",
  "description": "VIP Guest List",
  "rows": 0,
  "columns": 0,
  "schema": {
    "columns": [ {
      "type": "STRING",
      "name": "Friend"
    }, {
      "type": "STRING",
      "name": "Attending"
    } ]
  },
  "owner": {
    "id": 27,
    "name": "DomoSupport"
  },
  "createdAt": "2016-06-21T17:20:36Z",
  "updatedAt": "2016-06-21T17:48:41Z",
"pdpEnabled": true,
  "policies": [ {
    "id": 8,
    "type": "user",
    "name": "Only Show Attendees",
    "filters": [ {
      "column": "Attending",
      "values": [ "TRUE" ],
      "operator": "EQUALS",
      "not": false
    } ],
    "users": [ 27 ],
    "groups": [ ]
  } ]
}

Delete a DataSet

Permanently deletes a DataSet from your Domo instance. This can be done for all DataSets, not just those created through the API.

Warning
This is destructive and cannot be reversed.

Definition

DELETE https://api.domo.com/v1/datasets/{DATASET_ID}

Arguments

Property Name Type Required Description
dataset_id string Required The ID of the DataSet to delete

Sample Request

See it in your language

See this sample request in Java and Python.
DELETE https://api.domo.com/v1/datasets/317970a1-6a6e-4f70-8e09-44cf5f34cf44
Authorization: bearer <your-valid-oauth-access-token>

Returns

Returns an empty response.

Sample Response

HTTP/1.1 204 No Content

Query a DataSet

Queries the data in an existing Domo DataSet

Definition

https://api.domo.com/v1/datasets/query/execute/{DATASET_ID}

Arguments

Property Name Type Required Description
dataset_id string Required The ID of the DataSet

Sample Request

POST https://api.domo.com/v1/datasets/query/execute/ce79d23f-ef7d-4318-9787-ebde54a8c5b4
Accept: application/json
Content-Type : application/json
Authorization: bearer <your-valid-oauth-access-token>

{"sql": "SELECT * FROM table"}

Returns

Returns data from the DataSet based on your SQL query.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "datasource": "ce79d23f-ef7d-4318-9787-ebde54a8c5b4",
    "columns": [
        "Description",
        "% of Inventory Value",
        "Cost",
        "Total Inventory Value",
        "_BATCH_ID_",
        "_BATCH_LAST_RUN_"
    ],
    "metadata": [
        {
            "type": "STRING",
            "dataSourceId": "ce79d23f-ef7d-4318-9787-ebde54a8c5b4",
            "maxLength": -1,
            "minLength": -1,
            "periodIndex": 0
        },
        {
            "type": "DOUBLE",
            "dataSourceId": "ce79d23f-ef7d-4318-9787-ebde54a8c5b4",
            "maxLength": -1,
            "minLength": -1,
            "periodIndex": 0
        },
        {
            "type": "LONG",
            "dataSourceId": "ce79d23f-ef7d-4318-9787-ebde54a8c5b4",
            "maxLength": -1,
            "minLength": -1,
            "periodIndex": 0
        },
        {
            "type": "LONG",
            "dataSourceId": "ce79d23f-ef7d-4318-9787-ebde54a8c5b4",
            "maxLength": -1,
            "minLength": -1,
            "periodIndex": 0
        },
        {
            "type": "DOUBLE",
            "dataSourceId": "ce79d23f-ef7d-4318-9787-ebde54a8c5b4",
            "maxLength": -1,
            "minLength": -1,
            "periodIndex": 0
        },
        {
            "type": "DATETIME",
            "dataSourceId": "ce79d23f-ef7d-4318-9787-ebde54a8c5b4",
            "maxLength": -1,
            "minLength": -1,
            "periodIndex": 0
        }
    ],
    "rows": [
        [
            "Maintenance",
            0.0035,
            35000,
            10000000,
            410,
            "2019-03-19T18:49:02"
        ],
        [
            "Labor",
            0.007,
            70000,
            10000000,
            410,
            "2019-03-19T18:49:02"
        ],
        [
            "Utilities",
            0.0087,
            87000,
            10000000,
            410,
            "2019-03-19T18:49:02"
        ],
        [
            "Space",
            0.025,
            250000,
            10000000,
            410,
            "2019-03-19T18:49:02"
        ]
    ],
    "numRows": 4,
    "numColumns": 6,
    "fromcache": true
}

List DataSets

Get a list of all DataSets in your Domo instance.

Definition

GET https://api.domo.com/v1/datasets

Arguments

Property Name Type Required Description
sort string optional The DataSet field to sort by. Fields prefixed with a negative sign reverses the sort (i.e. '-name' does a reverse sort by the name of the DataSets)
limit long optional The amount of DataSet to return in the list. The default is 50 and the maximum is 50.
offset long optional The offset of the DataSet ID to begin list of users within the response.

Sample Request

See it in your language

See this sample request in Java and Python.
GET https://api.domo.com/v1/datasets?sort=name&offset=20&limit=10
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

Returns

Returns all DataSet objects that meet argument criteria from original request.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 948

[ {
  "id": "08a061e2-12a2-4646-b4bc-20beddb403e3",
  "name": "Questions regarding Euclid's Fundamental Theorem of Arithmetic",
  "rows": 1,
  "columns": 6,
  "createdAt": "2015-12-10T07:06:14Z",
  "updatedAt": "2016-02-29T20:56:20.567Z"
}, {
  "id": "317970a1-6a6e-4f70-8e09-44cf5f34cf44",
  "name": "Ideas Regarding Physics",
  "description": "Notes",
  "rows": 1289280,
  "columns": 9,
  "createdAt": "2013-09-24T20:51:48Z",
  "updatedAt": "2016-02-29T20:56:07.619Z"
}, {
  "id": "cc22901d-c856-47c5-89a3-5228a4fa5663",
  "name": "Rene Descartes Mentions",
  "description": "",
  "rows": 194723231,
  "columns": 12,
  "createdAt": "2014-05-01T22:01:17Z",
  "updatedAt": "2016-02-29T20:56:05.034Z"
}, {
  "id": "36ea3481-5b90-4181-a4a8-4d9388e85d9e",
  "name": "Symbolic Logic",
  "description": "",
  "rows": 349660,
  "columns": 12,
  "createdAt": "2014-11-26T18:29:09Z",
  "updatedAt": "2016-02-29T20:55:50.337Z"
} ]

Import data into DataSet

Import data into a DataSet in your Domo instance. This request will replace the data currently in the DataSet.

Known limitation
The only supported content type is currently CSV format.
Best practices
To upload data in CSV format, the Domo specification used for representing data grids in CSV format closely follows the RFC standard for CSV (RFC-4180). For more details on correct CSV formatting, click here.

Definition

PUT https://api.domo.com/v1/datasets/{DATASET_ID}/data

Arguments

Property Name Type Required Description
dataset_id string Required The ID of the DataSet to have data imported

Sample Request

See it in your language

See this sample request in Java and Python.
PUT https://api.domo.com/v1/datasets/317970a1-6a6e-4f70-8e09-44cf5f34cf44/data
Content-Type: text/csv
Authorization: bearer <your-valid-oauth-access-token>

1,2,3
4,5,6
7,8,92

Returns

Returns a response of success or error for the outcome of data being imported into DataSet.

Sample Response

HTTP/1.1 204 No Content

Export data from DataSet

Export data from a DataSet in your Domo instance.

Known limitation
Data types will be exported as they are currently stored in the dataset. In addition, the only supported export type is CSV.

Definition

GET https://api.domo.com/v1/datasets/{DATASET_ID}/data

Arguments

Property Name Type Required Description
dataset_id string Required The ID of the DataSet to download data
includeHeader boolean optional Include table header
fileName string optional The filename of the exported csv

Sample Request

See it in your language

See this sample request in Java and Python.
GET https://api.domo.com/v1/datasets/317970a1-6a6e-4f70-8e09-44cf5f34cf44/data?includeHeader=true&fileName=data-dump.csv
Accept: text/csv
Authorization: bearer <your-valid-oauth-access-token>

Returns

Returns a raw CSV in the response body or error for the outcome of data being exported into DataSet.

Sample Response

HTTP/1.1 204 No Content

Retrieve a Personalized Data Permission (PDP) policy

Retrieve a policy from a DataSet within Domo. A DataSet is required for a PDP policy to exist.

Definition

GET https://api.domo.com/v1/datasets/{DATASET_ID}/policies/{PDP_ID}

Arguments

Property Name Type Required Description
pdp_id string Required The ID of the PDP policy to download data
dataset_id string Required The ID of the DataSet associated to the PDP policy

Sample Request

See it in your language

See this sample request in Java and Python.
GET https://api.domo.com/v1/datasets/4405ff58-1957-45f0-82bd-914d989a3ea3/policies/8
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

Returns

Returns a subset of the DataSet object specific to the data permission policy.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 234

{
  "id" : 8,
  "type" : "user",
  "name" : "Only Show Attendees",
  "filters" : [ {
    "column" : "Attending",
    "values" : [ "TRUE" ],
    "operator" : "EQUALS",
    "not" : false
  } ],
  "users" : [ 27 ],
  "groups" : [ ]
}

Create a Personalized Data Permission (PDP) policy

Create a PDP policy for user and or group access to data within a DataSet.  Users and groups must exist before creating PDP policy.

Known limitation
The number of characters for the list of values for a single PDP policy, including a delimiter character for each value, must be less than 255 characters.

Definition

POST https://api.domo.com/v1/datasets/{DATASET_ID}/policies

Arguments

Property Name Type Required Description
dataset_id string Required The ID of the DataSet associated to the PDP policy
name String Required Name of the Policy
filters[].column String Required Name of the column to filter on
filters[].not Boolean Required Determines if NOT is applied to the filter operation
filters[].operator String Required Matching operator (EQUALS)
filters[].values[] String Required Values to filter on
type String Required Type of policy (user or system)
users Array Required List of user IDs the policy applies to
groups Array Required List of group IDs the policy applies to

Sample Request

See it in your language

See this sample request in Java and Python.
POST https://api.domo.com/v1/datasets/4405ff58-1957-45f0-82bd-914d989a3ea3/policies
Content-Type: application/json
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

{
  "name": "Only Show Attendees",
  "filters": [ {
    "column": "Attending",
    "values": [ "TRUE" ],
    "operator": "EQUALS"
  } ],
  "users": [ 27 ]
}

Returns

Returns a subset of the DataSet object specific to the data permission policy.

Sample Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id" : 8,
  "type": "user",
  "name": "Only Show Attendees",
  "filters": [ {
    "column": "Attending",
    "values": [ "TRUE" ],
    "operator": "EQUALS",
    "not": false
  } ],
  "users": [ 27 ],
  "groups": [ ]
}

Update a Personalized Data Permission (PDP) policy

Update the specific PDP policy for a DataSet by providing values to parameters passed.

Known limitation
The number of characters for the list of values for a single PDP policy, including a delimiter character for each value, must be less than 255 characters.

Definition

PUT https://api.domo.com/v1/datasets/{DATASET_ID}/policies/{PDP_ID}

Arguments

Property Name Type Required Description
pdp_id string Required The ID of the PDP policy to download data
dataset_id string Required The ID of the DataSet associated to the PDP policy
name String - Name of the Policy
filters[].column String - Name of the column to filter on
filters[].not Boolean - Determines if NOT is applied to the filter operation
filters[].operator String - Matching operator (EQUALS)
filters[].values[] String - Values to filter on
type String - Type of policy (user or system)
users Array - List of user IDs the policy applies to
groups Array - List of group IDs the policy applies to

Sample Request

See it in your language

See this sample request in Java and Python.
PUT https://api.domo.com/v1/datasets/4405ff58-1957-45f0-82bd-914d989a3ea3/policies/8
Content-Type: application/json
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

{
  "name" : "Not Attending",
  "filters" : [ {
    "column" : "Attending",
    "values" : [ "TRUE" ],
    "operator" : "EQUALS",
    "not" : true
  } ]
}

Returns

Returns a subset of the DataSet object specific to the data permission policy.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id" : 8,
  "type" : "user",
  "name" : "Not Attending",
  "filters" : [ {
    "column" : "Attending",
    "values" : [ "TRUE" ],
    "operator" : "EQUALS",
    "not" : true
  } ],
  "users" : [ 27 ],
  "groups" : [ ]
}

Delete a Personalized Data Permission (PDP) policy

Permanently deletes a PDP policy on a DataSet in your Domo instance.

Warning
This is destructive and cannot be reversed.

Definition

DELETE https://api.domo.com/v1/datasets/{DATASET_ID}/policies/{PDP_ID}

Arguments

Property Name Type Required Description
pdp_id string Required The ID of the PDP policy to delete
dataset_id string Required The ID of the DataSet associated to the PDP policy

Sample Request

See it in your language

See this sample request in Java and Python.
DELETE https://api.domo.com/v1/datasets/4405ff58-1957-45f0-82bd-914d989a3ea3/policies/8
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

Returns

Returns a DataSet and PDP object and parameter of success or error based on whether the Personalized Data Permission (PDP) policy ID being valid.

Sample Response

HTTP/1.1 204 No Content

List Personalized Data Permission (PDP) policies

List the Personalized Data Permission (PDP) policies for a specified DataSet.

Definition

GET https://api.domo.com/v1/datasets/{DATASET_ID}/policies

Arguments

Property Name Type Required Description
dataset_id string Required The ID of the DataSet associated to the PDP policy

Sample Request

See it in your language

See this sample request in Java and Python.
GET https://api.domo.com/v1/datasets/4405ff58-1957-45f0-82bd-914d989a3ea3/policies
Accept: application/json
Authorization: bearer <your-valid-oauth-access-token>

Returns

Returns all PDP policies that are applied to the DataSet specified in request.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 234

[ {
  "id" : 8,
  "type" : "user",
  "name" : "Only Show Attendees",
  "filters" : [ {
    "column" : "Attending",
    "values" : [ "TRUE" ],
    "operator" : "EQUALS",
    "not" : false
  } ],
  "users" : [ 27 ],
  "groups" : [ ]
} ]