Rest V1 Usage

Table of contents

• General Functionality
  • A note on authentication
  • Content Type and Communication
  • Errors
  • Dates
  • Empty Fields
  • Pagination
• Resources
  • Performance Result
    • Objects
    • Endpoints
      • Get A Performance Result By ID
      • Delete A Performance Result By ID
      • Get Performance Results By Task ID
      • Get Count of Performance Results By Task ID
      • Get Performance Results By Task Name
      • Get Performance Results By Version
      • Get Performance Result With Children By ID
  • Buildlogger Log
    • Objects
    • Endpoints
      • Get A Log By ID
      • Get Log Metadata by ID
      • Get Logs By Task ID
      • Get Logs By Task ID And Group ID
      • Get Log Metadata By Task ID
      • Get Logs By Test Name
      • Get Log Metadata By Test Name
      • Get Logs By Test Name And Group ID
  • System Metric
    • Objects
    • Endpoints
      • Get A System Metric By Task ID
  • Test Result
    • Objects
    • Endpoints
      • Get Merged Task Test Results
      • Get Merged Task Test Results Stats
      • Get Merged Failed Test Sample

General Functionality

A note on authentication

Though most of these REST endpoints do not require authentication to access, those that do will return a 404 if no authentication headers are sent, if the username is invalid, or if the API key is incorrect for the user. Set the two headers, Api-User and Api-Key, with the username and API key, respectively.

Content Type and Communication

The API accepts and returns all results in JSON. Some resources also allow URL parameters to provide additional specificity to a request.

Errors

When an error is encountered during a request, the API returns a JSON object with the HTTP status code and a message describing the error of the form:

{
 "status": <http_status_code>,
 "error": <error message>
}

Dates

Date fields are returned ISO-8601 UTC extended format. They contain three fractional seconds with a ‘dot’ separator. All dates are stored in UTC time.

Empty Fields

A returned object may omit empty fields.

Pagination

API Routes that fetch many objects return them in a JSON array and support paging through subsets of the total result set. When there are additional results for the query, access to them is populated in a Link HTTP header. This header has the form:

"Link" : <http://<EVERGREEN_HOST>/rest/v2/path/to/resource?start_at=<pagination_key>&limit=<objects_per_page>; rel="next"

<http://<EVERGREEN_HOST>/rest/v2/path/to/resource?start_at=<pagination_key>&limit=<objects_per_page>; rel="prev"

Resources

The API has a series of implemented objects that it returns depending on the queried endpoint.

Performance Result

A performance result represents the data generated and used by Evergreen's performance tests.

Objects

Performance Result

Name	Type	Description
name	string	Unique identifier of this performance result.
info	object	Performance Result Info object.
created_at	time	Time that the performance test was created.
completed_at	time	Time that the performance test completed.
artifacts	array	Array of Artifact Info objects.
rollups	object	Perf Rollups object.

Performance Result Info

Name	Type	Description
project	string	Name of the Evergreen project.
version	string	Evergreen version ID.
order	int	Evergreen order.
variant	string	Evergreen build variant.
task_name	string	Name of the Evergreen task.
task_id	string	Unique identifier for this task.
execution	int	Execution (run) of the task.
test_name	string	Name of the performance test.
trial	int	Run of this specific test.
parent	string	If a subtest, the unique identifier of the parent performance result.
tags	array	Array of strings representing any tags that are relevant for this test.
arguments	object	Mapping of arguments (such as thread level) to their values for this specific test run.

Artifact Info

Name	Type	Description
type	string	Type of Pail bucket (currently supports S3, GridFS, and Local implementations).
bucket	string	Name of the bucket.
path	string	Path to the artifact in the bucket.
format	string	Format of the data at path.
compression	string	Compression of the file at path.
schema	string	Schema of the file at path.
tags	array	Array of strings representing tags that are relevant for this specific artifact.
created_at	time	Time this artifact was created.

Perf Rollups

Name	Type	Description
stats	array	List of Perf Rollup Value objects.
processed_at	time	Most recent time these rollups were processed.
count	int	Total number of rollups (length of stats).
valid	bool	Whether the rollups in stats are valid or not.

Perf Rollup Value

Name	Type	Description
name	string	Name of the rollup.
val	int/float	Value of the rollup.
version	int	Version of the rollup.
user	bool	Whether the rollup was user submitted or not.

Endpoints

Get A Performance Result By ID

GET /perf/<id>

Fetches the performance result with the given ID.

Delete A Performance Result By ID

DELETE /perf/<id>

Deletes the performance result with the given ID. Authentication is required for this end point.

Get Performance Results By Task ID

GET /perf/task_id/<task_id>

Fetches the performance results with the given task ID. Results are sorted by the created_at field in descending order.

Parameters

Name	Type	Description
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.

Get Count of Performance Results By Task ID

GET /perf/task_id/<task_id>/<execution>/count

Returns a count of perf results under the task ID for designated execution without sending any additional data

Get Performance Results By Task Name

GET /perf/task_name/<task_name>

Fetches the performance results with the given task name. Results are sorted by the info.order field in descending order.

Parameters

Name	Type	Description
project	string	Name of the Evergreen project.
variant	string	Name of the Evergreen build variant.
started_after	string	Start date (included) of the targeted time interval. The format is "YYYY-MM-DD".
finished_before	string	End date (excluded) of the targeted time interval. The format is "YYYY-MM-DD".
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.
limit	int	Optional. Limit on the number of results returned, mostly used for pagination.
skip	int	Optional. The number of results to skip before returning results, mostly used for pagination. Users typically do not need to set this

Get Performance Results By Version

GET /perf/version/<version>

Fetches the performance results with the given version. Results are sorted by the created_at field in descending order.

Parameters

Name	Type	Description
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.
limit	int	Optional. Limit on the number of results returned, mostly used for pagination.
skip	int	Optional. The number of results to skip before returning results, mostly used for pagination. Users typically do not need to set this parameter directly.

Get Performance Result With Children By ID

GET /perf/children/<id>

Fetches the performance result and its children with the given ID. Results are sorted by the created_at field in descending order.

Parameters

Name	Type	Description
started_after	string	Start date (included) of the targeted time interval. The format is "YYYY-MM-DD".
finished_before	string	End date (excluded) of the targeted time interval. The format is "YYYY-MM-DD".
max_depth	int	Depth limit on child search. If set to -1, will search children without depth limit.
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.

Buildlogger Log

A buildlogger log represents log lines collected during an Evergreen task or test.

Objects

Log

Name	Type	Description
id	string	Unique identifier of this log.
info	object	Log Info object.
created_at	time	Time that the log was created.
completed_at	time	Time that the log was completed.
duration	float64	Total duration (in seconds) of the log.
artifact	object	Log Artifact Info object.

Log Info

Name	Type	Description
project	string	Name of the Evergreen project.
version	string	Version ID from Evergreen.
variant	string	Build variant from Evergreen.
task_name	string	Name of the Evergreen task.
task_id	string	Unique identifier for this task.
execution	int	Execution (run) of the task.
test_name	string	Name of the test.
trial	int	Run of this specific test.
process_name	string	Name of process the log is capturing.
format	string	Format of the log.
tags	array	Array of strings representing any tags that are relevant for this test, task, or log.
arguments	object	Mapping of arguments (such as thread level) to their values for this specific test run, task run, or log.
exit_code	int	Exit code of the process.

Log Artifact Info

Name	Type	Description
type	string	Bucket type (S3, local, etc).
prefix	string	Prefix in the bucket.
chunks	array	Array of Log Chunk Info objects.

Log Chunk Info

Name	Type	Description
key	string	Key of the file in the bucket containing this chunk.
num_lines	int	Number of log lines in this chunk.
start	time	First timestamp of this chunk.
end	time	Last timestamp of this chunk.

Endpoints

Get A Log By ID

GET /buildlogger/<id>

Fetches the log with the given ID, returned as text.

Parameters

Name	Type	Description
start	string	Optional. Start time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
end	string	Optional. End time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
print_priority	bool	Optional. If "true" the log lines will be returned prefixed with their priority.
print_time	bool	Optional. If "true" the log lines will be returned prefixed with their timestamp.
limit	int	Optional. Limit on the number of log lines to return.

Get Log Metadata by ID

GET /buildlogger/<id>/meta

Fetches the log metadata with the given id, returned as a Log object.

Get Logs By Task ID

GET /buildlogger/task_id/<task_id>

Fetches the logs with the given task ID, returned as text.

Parameters

Name	Type	Description
execution	int	Optional. Execution of the task. Defaults to the latest execution of the task.
proc_name	string	Optional. Name of the process.
start	string	Optional. Start time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
end	string	Optional. End time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
print_priority	bool	Optional. If "true" the log lines will be returned prefixed with their priority.
print_time	bool	Optional. If "true" the log lines will be returned prefixed with their timestamp.
limit	int	Optional. Limit on the number of log lines to return.
n	int	Optional. If set to anything greater than 0, will return the last N lines of the log.
paginate	bool	Optional. If "true", the logs will be paginated. Ignored if limit or n set.
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.

Get Logs By Task ID And Group ID

GET /buildlogger/task_id/{task_id}/group/{group_id}

Fetches the logs with the given task ID and group ID, returned as text.

Parameters

Name	Type	Description
execution	int	Optional. Execution of the task. Defaults to the latest execution of the task.
proc_name	string	Optional. Name of the process.
start	string	Optional. Start time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
end	string	Optional. End time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
print_priority	bool	Optional. If "true" the log lines will be returned prefixed with their priority.
print_time	bool	Optional. If "true" the log lines will be returned prefixed with their timestamp.
limit	int	Optional. Limit on the number of log lines to return.
paginate	bool	Optional. If "true", the logs will be paginated. Ignored if limit set.
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.

Get Log Metadata By Task ID

GET /buildlogger/task_id/<task_id>/meta

Fetches the log metadata with the given task ID, returned as a Log object.

Parameters

Name	Type	Description
execution	int	Optional. Execution of the task. Defaults to the latest execution of the task.
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.

Get Logs By Test Name

GET /buildlogger/test_name/{task_id}/{test_name}

Fetches the logs with the given task ID and test name, returned as text.

Parameters

Name	Type	Description
execution	int	Optional. Execution of the task. Defaults to the latest execution of the task.
proc_name	string	Optional. Name of the process.
start	string	Optional. Start time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
end	string	Optional. End time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
print_priority	bool	Optional. If "true" the log lines will be returned prefixed with their priority.
print_time	bool	Optional. If "true" the log lines will be returned prefixed with their timestamp.
limit	int	Optional. Limit on the number of log lines to return.
paginate	bool	Optional. If "true", the logs will be paginated. Ignored if limit set.
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.

Get Log Metadata By Test Name

GET /buildlogger/test_name/{task_id}/{test_name}/meta

Fetches the log metadata with the given task ID and test name, returned as a Log object.

Parameters

Name	Type	Description
execution	int	Optional. Execution of the task. Defaults to the latest execution of the task.
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.

Get Logs By Test Name And Group ID

GET /buildlogger/test_name/{task_id}/{test_name}/group/{group_id}

Fetches the logs with the given task ID, test name, and group ID, returned as text.

Parameters

Name	Type	Description
execution	int	Optional. Execution of the task. Defaults to the latest execution of the task.
start	string	Optional. The start time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
end	string	Optional. The end time of the targeted time interval in RFC3339 format ("YYYY-DD-MMTHH:MM:SS%2B00:00").
print_priority	bool	Optional. If "true" the log lines will be returned prefixed with their priority.
print_time	bool	Optional. If "true" the log lines will be returned prefixed with their timestamp.
limit	int	Optional. The limit on the number of log lines to return.
paginate	bool	Optional. If "true", the logs will be paginated. Ignored if limit set.
tags	string	Optional. Tags to include for search. Repeat the parameter key if assigning more than one value.

System Metric

A system metric represents time series data of a host runtime metric during an Evergreen task.

Objects

Metric Types

Name	Format	Description
disk_usage	FTDC	Information about the host disk usage.
process	JSON	Information about the processes running on the host.
uptime	FTDC	Information about the host uptime.

Endpoints

Get A System Metric By Task ID

GET /system_metrics/type/{task_id}/{type}

Fetches the system metric for the given task ID and type of metric. The format of the result depends on the metric type being requested.

Parameters

Name	Type	Description
execution	int	Optional. Execution of the task. Defaults to the latest execution of the task.

Test Result

A test result represents the outcome of a test run during an Evergreen task.

Objects

Test Results Task Options

Name	Type	Description
task_id	string	Unique identifier of the task.
execution	int	Execution (run) of the task.

Test Results Filter Options

Name	Type	Description
test_name	string	Optional. Test name filter, can be an exact match or a regular expression. The default behavior favors matching on the display test name, if it exists; to match only on the test name specify exclude_display_names. See https://github.com/google/re2/wiki/Syntax for more information on regular expression syntax.
exclude_display_names	bool	Optional. Exclude display test names when filtering on the specified test_name.
statuses	array	Optional. Array of strings representing status filters, each filter must be an exact match.
group_id	string	Optional. Group ID filter, must be an exact match.
sort	array	Optional. Array of Test Results Sort By objects where each element specifies a sort criteria. In the case of multiple sort criteria, precedence is dictated by the ordering of the elements.
base_tasks	array	Optional. Array of Test Results Task Options objects representing base tasks for comparison. If sorting on base_status is specified, this parameter must be set.
limit	int	Optional. Limit on the number of test results returned.
page	int	Optional. Pagination key. Invalid if limit is not greater than 0.

Test Results Sort By

Name	Type	Description
key	string	Key by which to sort the test results. Accepted values are start, duration, test_name, status, and base_status.
order_dsc	bool	Optional. Sort the specified key in descending order. Sort order defaults to ascending order.

Task Test Results

Name	Type	Description
stats	object	Task Test Results Stats object.
results	array	Array of Test Result objects.

Task Test Results Stats

Name	Type	Description
total_count	int	Total number of tests in this group of test results.
failed_count	int	Number of tests that failed in this group of test results.
filtered_count	int	Number of tests after applying a specific set of filters on this group of test results. Only returned for routes where filtering is allowed.

Test Result

Name	Type	Description
task_id	string	Unique identifier of the task that ran this test.
execution	int	Execution (run) of the task.
test_name	string	Unique name of this test within a task execution.
display_test_name	string	Optional human-readable name of the test. May not be unique within a task execution.
status	string	The outcome of the test.
base_status	string	The outcome of the test on the latest base task run, if applicable.
log_test_name	string	Test name identifier for the logs, if different than test_name.
log_url	string	Link to retrieve the test logs for this result.
raw_log_url	string	Link to retrieve the raw test logs for this result.
line_num	int	Line number in the test logs for this test.
task_create_time	time	Time the task was created.
test_start_time	time	Time the test started.
test_end_time	time	Time the test ended.

Endpoints

Get Merged Task Test Results

GET /test_results/tasks

Fetches the merged test results and aggregated statistics for the given (task ID, execution) pairs returned as a single Task Test Results object. Options are passed in as a JSON object in the request body.

Request Body

Name	Type	Description
tasks	array	Array of Task Test Results Options objects. At least one task must be specified.
filter	object	Optional. Test Results Filter Options object for filtering, sorting, and pagination.

Get Merged Task Test Results Stats

GET /test_results/tasks/stats

Fetches aggregated test results statistics of the given (task ID, execution) pairs, returned as a Task Test Results Stats object. Options are passed in as a JSON object in the request body.

Request Body

Name	Type	Description
tasks	array	Array of Task Test Results Options objects. At least one task must be specified.

Get Merged Failed Test Sample

GET /test_results/tasks/failed_sample

Fetches a sample of maximum size 10 of display test names that failed in the given (task ID, execution) pairs, returned as a JSON array of strings. Options are passed in as a JSON object in the request body.

Request Body

Name	Type	Description
tasks	array	Array of Task Test Results Options objects. At least one task must be specified.