Use the following methods to get and run reports that have been made accessible to the API.
Before accessing a report via the get_reports and run_report endpoints, you need to make your report accessible to the API. When creating a new report, you can do this by checking the Create this report: On-demand via the API checkbox.
Please note that 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 on the Reports tab.
Reports in the API Templates section are visible and executable using the get_reports and run_report endpoints respectively.
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
This endpoint requires TestRail 5.7 or later.
Returns a list of API available reports by the 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) |