API: Reports - TestRail

API: Reports

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

On this page:

    API Rate Limit

    Please note that the API is rate-limited on TestRail Cloud to ensure optimal performance for all users and may throttle requests. TestRail might also return a 429 Too Many Requests response, which you are expected to handle. Such a response also includes a Retry-After header indicating how many seconds to wait before you are allowed to submit the next request.

    To avoid rate limits on TestRail Cloud, try using bulk API endpoints (e.g. using as add_results_for_cases instead of add_results_for case), build a time delay into your API calls, or upgrade to TestRail Enterprise Cloud.

    Rate limits for TestRail Cloud are as follows:

    • 180 Requests per instance, per minute for TestRail Cloud Professional subscriptions.
    • 300 Requests per instance, per minute for TestRail Cloud Enterprise subscriptions.

    No API rate limits are built into TestRail Server installations.

    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.

    info Please Note: 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 reports by project.

    Requires TestRail 5.7 or later.

    GET index.php?/api/v2/get_reports/:project_id
    :project_id 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": "[email protected]\r\[email protected]",
            "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 int 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

    200 Success, the reports are returned in the response
    400 Invalid or unknown project
    403 No access to the project

    run_report

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

    Requires TestRail 5.7 or later.

    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

    200 Success, the reports are returned in the response
    400 Invalid report template ID
    403 No access to the project