Analytics

Report Runs

Every time a report is run, a full copy of the report with all its components is saved. Each report run is saved as a separate URL and it is possible to see a complete history of all the runs for any given report in Mode.

You can use the runs resource to trigger a new run of a report or retrieve history of all runs for a single report.

Report Run object

Properties
token required	string
state required	string enum: pending enqueued cancelled failed succeeded completed running_notebook
parameters
created_at required	string
updated_at required	string
completed_at required	string
purge_started_at required	string
purge_completed_at required	string
python_state	string enum: none pending failed submitted succeeded
form_fields	array
is_latest_report_run required	string
is_latest_successful_report_run required	string
report_has_failures_since_last_success required	string
pusher_channel_name	string
_links required	object

Links

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
clone
content
embed
executed_by
latest_successful_report_run_api_url
pdf_export
preview
python_cell_runs

query_runs
report
report_schedule
self
share
web_clone
web_edit_dataset
web_external_url

{
  "token": "f2lkg3hwjj9",
  "state": "enqueued",
  "parameters": {},
  "created_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "updated_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "completed_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "purge_started_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "purge_completed_at": "YYYY-MM-DDTHH:MM:SS.msZ",
  "python_state": "none",
  "form_fields": [],
  "_links": {
    "self": {
      "href": "occaecat eiusmod",
      "templated": false
    },
    "preview": {
      "href": "nisi veniam",
      "templated": false
    },
    "account": {
      "href": "in culpa Duis sit Ut",
      "templated": false
    },
    "report_schedule": {
      "href": "aliqua d",
      "templated": false
    },
    "executed_by": {
      "href": "ut",
      "templated": false
    },
    "report": {
      "href": "ad nulla",
      "templated": false
    },
    "clone": {
      "href": "fugiat velit est ex commodo",
      "templated": false
    },
    "query_runs": {
      "href": "minim deserunt",
      "templated": false
    },
    "python_cell_runs": {
      "href": "eu Lorem en",
      "templated": false
    },
    "pdf_export": {
      "href": "tempor",
      "templated": false
    },
    "content": {
      "href": "eiusmod ipsum consectetur magna",
      "templated": false
    },
    "share": {
      "href": "",
      "templated": false
    },
    "embed": {
      "href": "adipisicing ullamco ",
      "templated": false
    },
    "web_clone": {
      "href": "elit",
      "templated": false
    },
    "web_external_url": {
      "href": "anim irure fugiat qui",
      "templated": false
    }
  },
  "_embedded": {}
}

Get a report run

To retrieve a representation of a report run, send a GET request to the runs resource.

URL Params
account required	string	`Account` (`Workspace` or `User`) username
report required	string	`Report` token
run required	string	`ReportRun` token

Responses
200	ReportRun response
401	Unauthorized
404	ReportRun not found

GET /{account}/reports/{report}/runs/{run}

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

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}/reports/{report}/runs')
puts response

from urllib2 import Request, urlopen

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

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

var request = new XMLHttpRequest();

request.open('GET', 'https://app.mode.com/api/{account}/reports/{report}/runs');

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();

Get report run duplication status

To retrieve the status of a report run duplication operation, send a GET request to the report run duplicate resource passing through the report run duplicate token. Returns a representation of the report run duplicate.

URL Params
account required	string	`Account` (`Workspace` or `User`) username
report required	string	`Report` token
run required	string	`ReportRun` token
duplicate required	string	`ReportRunDuplicate` token

Responses
200	ReportRunDuplicate response
401	Unauthorized
404	ReportRunDuplicate not found

GET /{account}/reports/{report}/runs/{run}/duplicates/{duplicate}

curl --include \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates/{duplicate}'

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}/reports/{report}/runs/{run}/duplicates/{duplicate}')
puts response

from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates/{duplicate}', headers=headers)

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

var request = new XMLHttpRequest();

request.open('GET', 'https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates/{duplicate}');

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 report runs

To get a list of all runs for a given report, send a GET request to the runs resource.

URL Params
account required	string	`Account` (`Workspace` or `User`) username
report required	string	`Report` token

Query Params
filter	string	Returns a filtered list of `Runs`s for a `Report` 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=updated_at.lt.2019-10-23T06:23:01Z` returns all `Runs` in a space created before that date.
order	string	With the `order` param, returns all `ReportRun`s for a `Report` ordered by their `created_at` or `updated_at` timestamps
order_by	string	With the `order_by` param, returns all `ReportRun`s for a `Report` ordered in `asc` or `desc` order

Responses
200	ReportRun collection response
401	Unauthorized
404	ReportRun not found

GET /{account}/reports/{report}/runs

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

# Optional Query Params:

  # Filter runs 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}/reports/{report}/runs?filter=created_at.gt.2019-12-19T10:21:12Z'

  # Order runs 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}/reports/{report}/runs?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}/reports/{report}/runs')
puts response

# Optional Query Params:

  # Filter runs 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}/reports/{report}/runs?filter=created_at.gt.2019-12-19T10:21:12Z')

  # Order runs 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}/reports/{report}/runs?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}/reports/{report}/runs', headers=headers)

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

# Optional Query Params:

  # Filter runs 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}/reports/{report}/runs?filter=created_at.gt.2019-12-19T10:21:12Z')

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

  request = Request('https://app.mode.com/api/{account}/reports/{report}/runs?order=asc&order_by=created_at')

var request = new XMLHttpRequest();

request.open('GET', 'https://app.mode.com/api/{account}/reports/{report}/runs');

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 reports 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}/reports/{report}/runs?filter=created_at.gt.2019-12-19T10:21:12Z');

  // Order reports 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}/reports/{report}/runs?order=asc&order_by=created_at');

Clone a report run

To clone a report run, send a POST request to the reports resource at clone, and specify the report run token.

Cloning is not currently supported with Workspace API keys. See help documentation for more information.

URL Params
account required	string	`Account` (`Workspace` or `User`) username
report required	string	`Report` token
run required	string	`ReportRun` token

Responses
200	Report response
400	Bad request
401	Unauthorized
404	ReportRun not found

POST /{account}/reports/{report}/runs/{run}/clone

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{account}/reports/{report}/runs/{run}/clone'

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)
               .post('https://app.mode.com/api/{account}/reports/{report}/runs/{run}/clone')
puts response

from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{account}/reports/{report}/runs/{run}/clone', headers=headers)

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

var request = require('request');

request({
  method: 'POST',
  url: 'https://app.mode.com/api/{account}/reports/{report}/runs/{run}/clone',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/hal+json'
  }}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});

Duplicate a report run

To duplicate a report run asynchronously, send a POST request to the report run duplicate resource specifying both the report and the report run tokens. To check the status of a report run duplication request and get the duplicated report token, see the documentation for GET report run duplication status.

URL Params
account required	string	`Account` (`Workspace` or `User`) username
report required	string	`Report` token
run required	string	`ReportRun` token

Query Params
collection_id	string	The token of a collection. Example: collection_id=875a93v22b93

Responses
200	ReportRunDuplicate response
400	Bad request
401	Unauthorized
404	ReportRun not found

POST /{account}/reports/{report}/runs/{run}/duplicates

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
  'https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates'

# Optional Query Params:

  # Move to a specific collection
  # `?collection_id={collection}`

  curl --include \
       --request POST \
       --header "Content-Type: application/json" \
       --header "Accept: application/hal+json" \
   'https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates?collection_id={collection}'

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)
               .post('https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates')
puts response

# Optional Query Params:

  # Move to a specific collection
  # `?collection_id={collection}`

    response = HTTP.basic_auth(user: username, pass: password)
                   .headers(headers)
                   .post('https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates?collection_id={collection}')

from urllib2 import Request, urlopen

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates', headers=headers)

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

# Optional Query Params:

  # Move to a specific collection
  # `?collection_id={collection}`

  request = Request('https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates?collection_id={collection}', headers=headers)

var request = require('request');

request({
  method: 'POST',
  url: 'https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/hal+json'
  }}, function (error, response, body) {
  console.log('Status:', response.statusCode);
  console.log('Headers:', JSON.stringify(response.headers));
  console.log('Response:', body);
});

// Optional Query Params:

  // Move to a specific collection
  // `?collection_id={collection}`

    request({
      method: 'POST',
      url: 'https://app.mode.com/api/{account}/reports/{report}/runs/{run}/duplicates?collection_id={collection}',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/hal+json'
      }}, function (error, response, body) {
      console.log('Status:', response.statusCode);
      console.log('Headers:', JSON.stringify(response.headers));
      console.log('Response:', body);
    });

Create a report run

To trigger a report run, send a POST request to the runs resource, specifying the report token. This call returns a representation of the resulting report run.

URL Params
account required	string	`Account` (`Workspace` or `User`) username
report required	string	`Report` token

POST Body Params Object: `parameters`
parameters		Custom parameter attributes

Responses
202	ReportRun Accepted
400	Bad request
401	Unauthorized
404	Report not found

POST /{account}/reports/{report}/runs

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/hal+json" \
     --data-binary "{
  \"parameters\": {
    \"user_id\": 123,
    \"location\": \"San Francisco\"
  }
}" \
'https://app.mode.com/api/{account}/reports/{report}/runs'

require 'http'

values = {
  parameters: {
    user_id: 123,
    location: 'San Francisco'
  }
}

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

response = HTTP.basic_auth(user: username, pass: password)
               .headers(headers)
               .post('https://app.mode.com/api/{account}/reports/{report}/runs', json: values)
puts response

from urllib2 import Request, urlopen

values = """
  {
    "parameters": {
      "user_id": 123,
      "location": "San Francisco"
    }
  }
"""

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/hal+json'
}
request = Request('https://app.mode.com/api/{account}/reports/{report}/runs', data=values, headers=headers)

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

var request = new XMLHttpRequest();

request.open('POST', 'https://app.mode.com/api/{account}/reports/{report}/runs');

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);
  }
};

var body = {
  'parameters': {
    'user_id': 123,
    'location': 'San Francisco'
  }
};

request.send(JSON.stringify(body));