Reports and Cross-Project Reports

Use the following methods to get and run single-project reports that have been made accessible to the API.

Before accessing a report via the API endpoints, you need to make your report accessible to the API. You can do this by creating a new report and checking the Create this report: On-demand via the API checkbox.

 

 

You cannot modify the Create this report: settings once the report has been saved. So, you won’t be able to change your existing scheduled reports to be accessible to the API.

Once you have created a report and checked the On-demand via the API checkbox, the report will be visible in the API Templates section tab, next to the other reports.

 

 

Reports in the API Templates section are visible and executable using the API endpoints described below.

 

The report may not be available immediately after being run, and the time the report takes before it is available can vary, especially for TestRail Server customers.

get_reports

Returns a list of API available single-project reports by project.

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

Parameters

Name Type Required Description
project_id integer true The ID of the project for which you want a list of API accessible reports

Response content

Please see below for a typical response:

[
    {
        "id": 1,
        "name": "Activity Summary (Cases) %date%",
        "description": null,
        "notify_user": true,
        "notify_link": false,
        "notify_link_recipients": null,
        "notify_attachment": false,
        "notify_attachment_recipients": "person1@example.com\r\nperson2@example.com",
        "notify_attachment_html_format": false,
        "notify_attachment_pdf_format": false,
        "cases_groupby": "day",
        "changes_daterange": "5",
        "changes_daterange_from": null,
        "changes_daterange_to": null,
        "suites_include": "1",
        "suites_ids": null,
        "sections_include": "1",
        "sections_ids": null,
        "cases_columns": {
            "cases:id": 75,
            "cases:title": 0,
            "cases:created_by": 125,
            "cases:updated_by": 125
        },
        "cases_filters": null,
        "cases_limit": 1000,
        "content_hide_links": false,
        "cases_include_new": true,
        "cases_include_updated": true
    }
]

The following system fields are always included in the response:

Name Type Description
id integer The unique ID for the report
name string Name of the report
description string Description of the report
notify_user boolean Indicates whether the author should be notified once the report has been executed
notify_link boolean Indicates whether emails with links to the report should be sent
notify_link_recipients string List of users to whom the report should be sent
notify_attachment boolean Indicates whether the report should be emailed as an attachment
notify_attachment_html_format boolean Indicates whether the report should be emailed in HTML format, if notify_ attachment is true
notify_attachment_pdf_format boolean Indicates whether the report should be emailed in PDF format, if notify_ attachment is true

Response codes

Status Code Description
200 Success (the reports are returned in the response)
400 Invalid or unknown project
403 No access to the project
429 TestRail Cloud only—Too many requests (see API rate limit)

 

run_report

 

This endpoint requires TestRail 5.7 or later.

Executes the report identified using the report_id parameter and returns URL‘s for accessing the report in HTML and PDF format.

GET index.php?/api/v2/run_report/{report_template_id}

Response content

{
    "report_url": "https://docs.testrail.com/index.php?/reports/view/383",
    "report_html": "https://docs.testrail.com/index.php?/reports/get_html/383",
    "report_pdf": "https://docs.testrail.com/index.php?/reports/get_pdf/383"
}   

Response codes

Status Code Description
200 Success (the reports are returned in the response)
400 Invalid report template ID
403 No access to the project
429 TestRail Cloud only—Too many requests (see API rate limit)

 

get_cross_project_reports

Returns all API available cross-project reports the user has access to - available for Enterprise license plans only.

GET index.php?/api/v2/get_cross_project_reports/

Parameters

Does not have an input parameter.

 

Response content

Please see below for a typical response:

[
    {
        "id": 1,
        "name": "Test Execution Projects Summary %date%",
        "description": null,
        "project_ids": [],
        "include_open_milestones": true,
        "include_completed_milestones": true,
        "include_open_runs_and_plans": true,
        "include_completed_runs_and_plans": true,
        "report_timeframe": "90 days",
        "included_statuses": "Passed, Blocked, Untested",
        "content_hide_links": false,
        "notify_user": true,
        "notify_link": false,
        "notify_link_recipients": null,
        "notify_attachment": false,
        "notify_attachment_recipients": "person1@example.com\r\nperson2@example.com",
        "notify_attachment_html_format": false,
        "notify_attachment_pdf_format": false
    },
    {
        "id": 2,
        "name": "Test Execution User Workload %date%",
        "description": null,
        "user_ids": [],
        "project_ids": [],
        "report_timeframe": "90 days",
        "include_open_runs_and_plans": true,
        "include_completed_runs_and_plans": true,
        "include_elapsed_test_time": true,
        "include_estimated_test_time": true,
        "sort_by": "alphabetical",
        "content_hide_links": false,
        "notify_user": true,
        "notify_link": false,
        "notify_link_recipients": null,
        "notify_attachment": false,
        "notify_attachment_recipients": "person1@example.com\r\nperson2@example.com",
        "notify_attachment_html_format": false,
        "notify_attachment_pdf_format": false
    }
]

The following system fields are always included in the response:

Name Type Description
id integer The unique ID for the report
name string Name of the report
description string Description of the report
project_ids list List of project IDs included in the report
user_ids list

List of user IDs included in the report

Available for User Workload only

include_elapsed_test_time boolean

Whether or not the test elapsed time is included

Available for User Workload only

include_estimated_test_time boolean

Whether or not the test estimated time is included

Available for User Workload only

sort_by string

Includes the selected sorting option

Available for User Workload only

include_open_milestones boolean Whether open milestones are included
include_completed_milestones boolean Whether completed milestones are included
include_open_runs_and_plans boolean Whether open runs and plans are included
include_completed_runs_and_plans boolean Whether completed runs and plans are included
report_timeframe date The timeframe selected for the execution of the report
included_statuses list The statuses selected for the execution of the report
notify_user boolean Indicates whether the author should be notified once the report has been executed
notify_link boolean Indicates whether emails with links to the report should be sent
notify_link_recipients string List of users to whom the report should be sent
notify_attachment boolean Indicates whether the report should be emailed as an attachment
notify_attachment_html_format boolean Indicates whether the report should be emailed in HTML format, if notify_ attachment is true
notify_attachment_pdf_format boolean Indicates whether the report should be emailed in PDF format, if notify_ attachment is true

Response codes

Status Code Description
200 Success (the reports are returned in the response)
403

TestRail Enterprise only. Access denied.

User role does not grant access.

429

TestRail Cloud only—Too many requests (see API rate limit)

 

run_cross_project_report

Executes the report identified using the report_template_id parameter and returns URL‘s for accessing the report in HTML and PDF format - available for Enterprise license plans only.

GET index.php?/api/v2/run_cross_project_report/{report_template_id}

Response content

{
    "report_url": "https://docs.testrail.com/index.php?/cross_project_reports/view/383",
    "report_html": "https://docs.testrail.com/index.php?/cross_project_reports/get_html/383",
    "report_pdf": "https://docs.testrail.com/index.php?/cross_project_reports/get_pdf/383"
}   

Response codes

Status Code Description
200 Success (the reports are returned in the response)
400 Invalid report template ID
403 No access to the project
429 TestRail Cloud only—Too many requests (see API rate limit)
Was this article helpful?
2 out of 23 found this helpful