Analytics

Datasets

Datasets are curated tables of data that can be reused across multiple reports. Every Dataset lives in a Collection and contains a SQL query.

You can use the dataset resource to manage individual Mode datasets.

Note: Spaces have been rebranded as Collections in Mode, but the API will continue to refer to spaces. The spaces object and resources are the same as Collections in the Mode UI.

Dataset object

Properties

token

required

string

id

required

integer

name

required

string

description

string

created_at

required

string

updated_at

required

string

published_at

required

string

edited_at

required

string

theme_id

integer

color_mappings

string

type

required

string

last_successful_sync_at

string

last_saved_at

required

string

archived

required

boolean

space_token

string

account_id

required

integer

account_username

required

string

public

required

boolean

full_width

boolean

manual_run_disabled

required

boolean

run_privately

required

boolean

drilldowns_enabled

required

boolean

layout

string

is_embedded

boolean

is_signed

boolean

shared

boolean

expected_runtime

required

number

last_successfully_run_at

required

string

last_run_at

required

string

web_preview_image

string

last_successful_run_token

required

string

github_link

string

query_count

required

string

max_query_count

required

string

chart_count

string

runs_count

required

string

schedules_count

required

string

query_preview

required

string

view_count

required

string

_links

required

object

All resource responses contain a set of links that describe other related resources or actions that you can take on this resource. A link is comprised of two main pieces: its name (which describes its relationship to this resource) and its href (the URL of the related action or resource). All resources have at least a _self link which is the URL that will return a representation of this resource.

  • account
  • creator
  • csv_export
  • dataset_dependencies
  • dbt_metadata
  • embed_key
  • last_run
  • last_successful_github_sync
  • last_successful_run
  • perspective_email_subscription_memberships
  • python_notebook
  • python_visualizations
  • queries
  • report_filters
  • report_index_web
  • report_pins
  • report_run
  • report_runs
  • report_schedules
  • report_subscriptions
  • report_theme
  • self
  • share
  • space
  • space_links
  • star
  • validate_email_subscriber
  • web
  • web_edit
  • web_external_url
  • web_report_runs
{
  "token": "flkgj3h2f24",
  "id": 73267438,
  "name": "culpa mollit",
  "created_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "updated_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "edited_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "theme_id": 37094832,
  "color_mappings": "nulla et esse ut",
  "last_successful_sync_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "last_saved_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "archived": false,
  "account_id": 51699936,
  "account_username": "labore dolore consequat anim non",
  "public": false,
  "full_width": true,
  "manual_run_disabled": false,
  "run_privately": true,
  "drilldowns_enabled": true,
  "layout": "id",
  "is_embedded": true,
  "is_signed": true,
  "shared": true,
  "expected_runtime": 90198048.20198965,
  "last_successfully_run_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "last_run_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "web_preview_image": "Ut",
  "last_successful_run_token": "af2g34t4hyrnt",
  "query_count": "anim adipisicing Lorem occaecat",
  "chart_count": "est elit",
  "schedules_count": "culpa id eiusmod dolore",
  "query_preview": "fugiat",
  "description": "Ut",
  "space_token": "fg32wrg534f",
  "flamingo_signature": "cillum sunt ea",
  "github_link": "veniam laborum",
  "_links": {
    "self": {
      "href": "commodo eu reprehenderit",
      "templated": false
    },
    "web": {
      "href": "cillum quis fugiat incididunt aute",
      "templated": false
    },
    "account": {
      "href": "Ut",
      "templated": false
    },
    "report_run": {
      "href": "Excepteur mollit irure",
      "templated": false
    },
    "queries": {
      "href": "occaecat magna sit Lorem",
      "templated": false
    },
    "report_runs": {
      "href": "cillum esse eu tempor",
      "templated": false
    },
    "report_pins": {
      "href": "et cillum ea",
      "templated": false
    },
    "report_schedules": {
      "href": "laborum adipisicing commodo",
      "templated": false
    },
    "python_visualizations": {
      "href": "sed ea",
      "templated": false
    },
    "embed_key": {
      "href": "aliquip commodo",
      "templated": false
    },
    "last_run": {
      "href": "ipsum ullamco laborum",
      "templated": false
    },
    "last_successful_run": {
      "href": "adipisicing in",
      "templated": false
    },
    "perspective_email_subscription_memberships": {
      "href": "magna laborum et ex amet",
      "templated": false
    },
    "report_theme": {
      "href": "qui labore dolor adipisicing",
      "templated": false
    },
    "last_successful_github_sync": {
      "href": "laborum in nostrud",
      "templated": false
    },
    "web_edit": {
      "href": "irure Excepteur consectetur",
      "templated": false
    },
    "web_external_url": {
      "href": "occaecat",
      "templated": false
    },
    "csv_export": {
      "href": "Lorem",
      "templated": false
    },
    "share": {
      "href": "dolore sunt ad",
      "templated": false
    },
    "web_report_runs": {
      "href": "sint dolore voluptate",
      "templated": false
    },
    "star": {
      "href": "velit elit Excepteur culpa",
      "templated": false
    },
    "space": {
      "href": "eu",
      "templated": false
    },
    "space_links": {
      "href": "ullamco",
      "templated": false
    },
    "report_filters": {
      "href": "pariatur ex proident Excepteur mollit",
      "templated": false
    },
    "report_subscriptions": {
      "href": "culpa",
      "templated": false
    },
    "python_notebook": {
      "href": "ea labore sed cillum",
      "templated": false
    },
    "validate_email_subscriber": {
      "href": "eu",
      "templated": false
    },
    "creator": {
      "href": "commodo Excepteur consequat Lorem ut",
      "templated": false
    }
  },
  "_embedded": {}
}

Get a Dataset

To retrieve information about a single Dataset, send a GET request including the Dataset token to the dataset resource.

URL Params

account

required
string Account (Workspace or User) username

dataset

required
string Dataset token
Responses

200

Dataset response

401

Unauthorized

404

Dataset not found

GET /{account}/datasets/{dataset}

curl --include \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{account}/datasets/{dataset}'
require 'http'

username = 'your_api_key'
password = 'your_api_secret'

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .get('https://app.mode.com/api/{account}/datasets/{dataset}')
puts response
from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{account}/datasets/{dataset}', headers=headers)

response_body = urlopen(request).read()
print(response_body)
var request = new XMLHttpRequest();

request.open('GET', 'https://app.mode.com/api/{account}/datasets/{dataset}');

request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/hal+json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();

List Datasets using a data source

To return a list of all Datasets using a given Data Source, send a GET request to the datasets resource.

URL Params

account

required
string Account (Workspace or User) username

data_source

required
string DataSource token
Query Params

filter

string Returns a filtered list of Datasets in a Space filtered by whether their created_at or updated_at timestamps are gt (greater than) or lt (less than) the datetime passed in ISO8601 format. Example: ?filter=created_at.gt.2019-10-23T06:23:01Z returns all Datasets in a space created after that date.

order

string With the order param, returns all Datasets in a Space ordered in asc or desc order. Example: ?order=asc&order_by=created_at

order_by

string With the order_by param, returns all Datasets in a Space ordered by their created_at or updated_at timestamps. Example: ?order_by=created_at&order=asc
Responses

200

Dataset collection response

401

Unauthorized

404

Dataset not found

GET /{account}/data_sources/{data_source}/datasets

curl --include \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{account}/data_sources/{data_source}/datasets'

# Optional Query Params:

  # Filter Datasets by when they were created or updated
  # '?filter={created_at|updated_at}.{gt|lt}.{YYYY-MM-DDTHH:MM:SSZ}'

  curl --include \
       --header "Content-Type: application/json" \
       --header "Accept: application/hal+json" \
    'https://app.mode.com/api/{account}/data_sources/{data_source}/datasets?filter=created_at.gt.2019-12-19T10:21:12Z'

  # Order Datasets by when they were created or updated
  # '?order={asc|desc}&order_by={created_at|updated_at}'

  curl --include \
       --header "Content-Type: application/json" \
       --header "Accept: application/hal+json" \
    'https://app.mode.com/api/{account}/data_sources/{data_source}/datasets?order=asc&order_by=created_at'
require 'http'

username = 'your_api_key'
password = 'your_api_secret'

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .get('https://app.mode.com/api/{account}/data_sources/{data_source}/datasets')
puts response

# Optional Query Params:

  # Filter Datasets by when they were created or updated
  # '?filter={created_at|updated_at}.{gt|lt}.{YYYY-MM-DDTHH:MM:SSZ}'

  response = HTTP.basic_auth(user: username, pass: password)
                 .headers(headers)
                 .get('https://app.mode.com/api/{account}/data_sources/{data_source}/datasets?filter=created_at.gt.2019-12-19T10:21:12Z')

  # Order Datasets by when they were created or updated
  # '?order={asc|desc}&order_by={created_at|updated_at}'

  response = HTTP.basic_auth(user: username, pass: password)
                 .headers(headers)
                 .get('https://app.mode.com/api/{account}/data_sources/{data_source}/datasets?order=asc&order_by=created_at')
from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{account}/data_sources/{data_source}/datasets', headers=headers)

response_body = urlopen(request).read()
print(response_body)

# Optional Query Params:

  # Filter Datasets by when they were created or updated
  # '?filter={created_at|updated_at}.{gt|lt}.{YYYY-MM-DDTHH:MM:SSZ}'

  request = Request('https://app.mode.com/api/{account}/data_sources/{data_source}/datasets?filter=created_at.gt.2019-12-19T10:21:12Z')

  # Order Datasets by when they were created or updated
  # '?order={asc|desc}&order_by={created_at|updated_at}'

  request = Request('https://app.mode.com/api/{account}/data_sources/{data_source}/datasets?order=asc&order_by=created_at')
var request = new XMLHttpRequest();

request.open('GET', 'https://app.mode.com/api/{account}/data_sources/{data_source}/datasets');

request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/hal+json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();

// Optional Query Params:

  // Filter Datasets by when they were created or updated
  // '?filter={created_at|updated_at}.{gt|lt}.{YYYY-MM-DDTHH:MM:SSZ}'

  request.open('GET', 'https://app.mode.com/api/{account}/data_sources/{data_source}/datasets?filter=created_at.gt.2019-12-19T10:21:12Z');

  // Order Datasets by when they were created or updated
  // '?order={asc|desc}&order_by={created_at|updated_at}'

  request.open('GET', 'https://app.mode.com/api/{account}/data_sources/{data_source}/datasets?order=asc&order_by=created_at');

List Datasets for a space

To return a list of all Datasets in a given Collection, send a GET request to the dataset resource.

Note: Spaces have been rebranded as Collections in Mode, but the API will continue to refer to spaces. The spaces object and resources are the same as Collections in the Mode UI.

URL Params

account

required
string Account (Workspace or User) username

space

required
string Space token
Query Params

filter

string Returns a filtered list of Datasets in a Space filtered by whether their created_at or updated_at timestamps are gt (greater than) or lt (less than) the datetime passed in ISO8601 format. Example: ?filter=created_at.gt.2019-10-23T06:23:01Z returns all Datasets in a space created after that date.

order

string With the order param, returns all Datasets in a Space ordered in asc or desc order. Example: ?order=asc&order_by=created_at

order_by

string With the order_by param, returns all Datasets in a Space ordered by their created_at or updated_at timestamps. Example: ?order_by=created_at&order=asc
Responses

200

Dataset collection response

401

Unauthorized

404

Dataset not found

GET /{account}/spaces/{space}/datasets

curl --include \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{account}/spaces/{space}/datasets'

# Optional Query Params:

  # Filter datasets by when they were created or updated
  # '?filter={created_at|updated_at}.{gt|lt}.{YYYY-MM-DDTHH:MM:SSZ}'

  curl --include \
       --header "Content-Type: application/json" \
       --header "Accept: application/hal+json" \
    'https://app.mode.com/api/{account}/spaces/{space}/datasets?filter=created_at.gt.2019-12-19T10:21:12Z'

  # Order datasets by when they were created or updated
  # '?order={asc|desc}&order_by={created_at|updated_at}'

  curl --include \
       --header "Content-Type: application/json" \
       --header "Accept: application/hal+json" \
    'https://app.mode.com/api/{account}/spaces/{space}/datasets?order=asc&order_by=created_at'
require 'http'

username = 'your_api_key'
password = 'your_api_secret'

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .get('https://app.mode.com/api/{account}/spaces/{space}/datasets')
puts response

# Optional Query Params:

  # Filter datasets by when they were created or updated
  # '?filter={created_at|updated_at}.{gt|lt}.{YYYY-MM-DDTHH:MM:SSZ}'

  response = HTTP.basic_auth(user: username, pass: password)
                 .headers(headers)
                 .get('https://app.mode.com/api/{account}/spaces/{space}/datasets?filter=created_at.gt.2019-12-19T10:21:12Z')

  # Order datasets by when they were created or updated
  # '?order={asc|desc}&order_by={created_at|updated_at}'

  response = HTTP.basic_auth(user: username, pass: password)
                 .headers(headers)
                 .get('https://app.mode.com/api/{account}/spaces/{space}/datasets?order=asc&order_by=created_at')
from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{account}/spaces/{space}/datasets', headers=headers)

response_body = urlopen(request).read()
print(response_body)

# Optional Query Params:

  # Filter Datasets by when they were created or updated
  # '?filter={created_at|updated_at}.{gt|lt}.{YYYY-MM-DDTHH:MM:SSZ}'

  request = Request('https://app.mode.com/api/{account}/spaces/{space}/datasets?filter=created_at.gt.2019-12-19T10:21:12Z')

  # Order Datasets by when they were created or updated
  # '?order={asc|desc}&order_by={created_at|updated_at}'

  request = Request('https://app.mode.com/api/{account}/spaces/{space}/datasets?order=asc&order_by=created_at')
var request = new XMLHttpRequest();

request.open('GET', 'https://app.mode.com/api/{account}/spaces/{space}/datasets');

request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('Accept', 'application/hal+json');

request.onreadystatechange = function () {
  if (this.readyState === 4) {
    console.log('Status:', this.status);
    console.log('Headers:', this.getAllResponseHeaders());
    console.log('Body:', this.responseText);
  }
};

request.send();

// Optional Query Params:

  // Filter Datasets by when they were created or updated
  // '?filter={created_at|updated_at}.{gt|lt}.{YYYY-MM-DDTHH:MM:SSZ}'

  request.open('GET', 'https://app.mode.com/api/{account}/spaces/{space}/datasets?filter=created_at.gt.2019-12-19T10:21:12Z');

  // Order Datasets by when they were created or updated
  // '?order={asc|desc}&order_by={created_at|updated_at}'

  request.open('GET', 'https://app.mode.com/api/{account}/spaces/{space}/datasets?order=asc&order_by=created_at');

Update a Dataset

To update a Dataset, send a PATCH request including the username and corresponding Dataset token to the datasets resource.

URL Params

account

required
string Account (Workspace or User) username

dataset

required
string Dataset token
POST Body Params

Object: report

name

string The name of the report

Example: Kanto Region Diaspora

description

string A description of the report in question

Example: An analysis of all the creatures living in the region. Please contribute any missing data. Pocket version coming soon.

space_token

string The token of the space this report will be moved to

Example: 5a4177a2902c

Responses

200

Dataset response

401

Unauthorized

404

Dataset not found

PATCH /{account}/datasets/{dataset}

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
     --data-binary "{
  \"report\": {
    \"name\": \"Kanto Region Diaspora\",
    \"description\": \"An analysis of all the creatures living in the region. Please contribute any missing data. Pocket version coming soon.\",
    \"space_token\": \"5a4177a2902c\"
  }
}" \
'https://app.mode.com/api/{account}/datasets/{dataset}'
require 'http'

values = {
  report: {
    name: 'Kanto Region Diaspora',
    description: 'An analysis of all the creatures living in the region. Please contribute any missing data. Pocket version coming soon.',
    space_token: '5a4177a2902c'
  }
}

headers = {
  content_type: 'application/json',
  accept: 'application/hal+json'
}

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .patch('https://app.mode.com/api/{account}/datasets/{dataset}', json: values)
puts response
from urllib2 import Request, urlopen

values = """
  {
    "report": {
      "name": "Kanto Region Diaspora",
      "description": "An analysis of all the creatures living in the region. Please contribute any missing data. Pocket version coming soon.",
      "space_token": "5a4177a2902c"
    }
  }
"""

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{account}/datasets/{dataset}', data=values, headers=headers)
request.get_method = lambda: 'PATCH'

response_body = urlopen(request).read()
print(response_body)
var request = require('request');

request({
  method: 'PATCH',
  url: 'https://app.mode.com/api/{account}/datasets/{dataset}',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/hal+json'
  },
  body: "{  \"report\": {    \"name\": \"Kanto Region Diaspora\",    \"description\": \"An analysis of all the creatures living in the region. Please contribute any missing data. Pocket version coming soon.\",    \"space_token\": \"5a4177a2902c\"  }}"
}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});