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

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

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 Runss 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 ReportRuns for a Report ordered by their created_at or updated_at timestamps

order_by

string With the order_by param, returns all ReportRuns 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);
    });

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

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