API: Users - TestRail

API: Users

Use the following API methods to request details about users.

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.

    get_user

    Returns an existing user.

    GET index.php?/api/v2/get_user/:user_id
    :user_id The ID of the user

    Response content

    {
	"email": "[email protected]",
	"id": 1,
	"is_active": true,
	"name": "Alexis Gonzalez",
	"role_id": "1",
	"role": "Lead"
}

    The following fields are included in the response

    Name Type Description
    email string The email address of the user as configured in TestRail
    id int The unique ID of the user
    is_active bool True if the user is active and false otherwise
    name string The full name of the user
    role_id int The unique ID of the user’s globally assigned role (Requires TestRail 6.4 or later)
    role string The Name of the user’s globally assigned role (Requires TestRail 6.4 or later)

     

    info Note: Any user can retrieve his/her own account information. Retrieving information for any other user requires administrator access.

    Response codes

    200 Success, the user is returned as part of the response
    400 Invalid or unknown user

    get_current_user

    Returns user details for the TestRail user making the API request (Requires TestRail 6.6 or later).

    GET index.php?/api/v2/get_current_user/:user_id

    Response content

    {
	"email": "[email protected]",
	"id": 1,
	"is_active": true,
	"name": "Alexis Gonzalez",
	"role_id": "1",
	"role": "Lead"
}

    The following fields are included in the response

    Name Type Description
    email string The email address of the user as configured in TestRail
    id int The unique ID of the user
    is_active bool True if the user is active and false otherwise
    name string The full name of the user
    role_id int The unique ID of the user’s globally assigned role (Requires TestRail 6.4 or later)
    role string The Name of the user’s globally assigned role (Requires TestRail 6.4 or later)

     

    info Note: Any user can retrieve his/her own account information. Retrieving information for any other user requires administrator access.

    Response codes

    200 Success, the user is returned as part of the response
    400 Invalid or unknown user

    get_user_by_email

    Returns an existing user by his/her email address.

    GET index.php?/api/v2/get_user_by_email&email=:email
    :email The email address to get the user for

    This method uses the same response format as get_user.

    info Note: Any user can retrieve his/her own account information. Retrieving information for any other user requires administrator access.

    Response codes

    200 Success, the user is returned as part of the response
    400/404 Invalid or unknown email address

    get_users

    Returns a list of users.

    GET index.php?/api/v2/get_users
    GET index.php?/api/v2/get_users/:project_id

    info Note: As of TestRail 6.6, only administrators can use get_users without a project_id parameter. Non-administrators are required to use the project_id parameter.

    :project_id The ID of the project for which you would like to retrieve user information. (Required for non-administrators. Requires TestRail 6.6 or later.)

     

    Please Note:

    • Non-administrators must include a project_id parameter.
    • When a project_id is omitted, all user information is returned.

    When a project_id parameter is used:

    • The role and role_id values returned will correspond to the user’s project-level access.
    • Inactive users are not included in the response.
    • Users without access to the project are not included in the response.

    Response content

    [
	{ "id": 1, "name": "Alexis Gonzalez", .. },
	{ "id": 2, "name": "Ciaran Davenport", .. },
	..
]

    The response includes an array of users. Each user in this list follows the same format as get_user.

    Response codes

    200 Success, the users are returned as part of the response
    400 Invalid project_id
    403 Insufficient permissions