Compare build performance
GET /v1/projects/{id}/builds/compare
Compares two builds by lower-is-better performance metrics. The response
contains P50/P95 values and signed percentage differences for frame time,
memory, GPU time, disk-read metrics (io.read_bytes, io.read_time_ms,
io.read_ops; SDK-fed, may be null), and map load time (load_time_ms,
from SDK map-load timing; may be null). CI can use the same data as
framedash perf-diff to gate a merge on build-over-build regressions.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Project UUID.
Query Parameters
Section titled “Query Parameters ”Known-good build_id to compare against.
New build_id under test. Must differ from baseline.
Time period in days.
Restrict the comparison to one map identifier.
Restrict the comparison to one platform.
Set to 1 to bypass the ~60s aggregation cache (used by run-profile-test).
Responses
Section titled “ Responses ”Build comparison result.
object
Build-over-build performance comparison.
object
Aggregated performance statistics for one build.
object
Average frame time in milliseconds.
Median frame time in milliseconds.
P95 frame time in milliseconds.
Average memory usage.
Median memory usage.
P95 memory usage.
Average GPU time in milliseconds, or null if unavailable.
Median GPU time in milliseconds, or null if unavailable.
P95 GPU time in milliseconds, or null if unavailable.
Average disk-read bytes per heartbeat window, or null if the SDK reported no io.* samples.
Median disk-read bytes per heartbeat window, or null if unavailable.
P95 disk-read bytes per heartbeat window, or null if unavailable.
Average disk-read time in milliseconds per heartbeat window, or null if unavailable.
Median disk-read time in milliseconds per heartbeat window, or null if unavailable.
P95 disk-read time in milliseconds per heartbeat window, or null if unavailable.
Average disk-read operations per heartbeat window, or null if unavailable.
Median disk-read operations per heartbeat window, or null if unavailable.
P95 disk-read operations per heartbeat window, or null if unavailable.
Average map load time in milliseconds (map_load events), or null if the build reported none.
Median map load time in milliseconds, or null if unavailable.
P95 map load time in milliseconds, or null if unavailable.
Aggregated performance statistics for one build.
object
Average frame time in milliseconds.
Median frame time in milliseconds.
P95 frame time in milliseconds.
Average memory usage.
Median memory usage.
P95 memory usage.
Average GPU time in milliseconds, or null if unavailable.
Median GPU time in milliseconds, or null if unavailable.
P95 GPU time in milliseconds, or null if unavailable.
Average disk-read bytes per heartbeat window, or null if the SDK reported no io.* samples.
Median disk-read bytes per heartbeat window, or null if unavailable.
P95 disk-read bytes per heartbeat window, or null if unavailable.
Average disk-read time in milliseconds per heartbeat window, or null if unavailable.
Median disk-read time in milliseconds per heartbeat window, or null if unavailable.
P95 disk-read time in milliseconds per heartbeat window, or null if unavailable.
Average disk-read operations per heartbeat window, or null if unavailable.
Median disk-read operations per heartbeat window, or null if unavailable.
P95 disk-read operations per heartbeat window, or null if unavailable.
Average map load time in milliseconds (map_load events), or null if the build reported none.
Median map load time in milliseconds, or null if unavailable.
P95 map load time in milliseconds, or null if unavailable.
Signed comparison for one lower-is-better performance metric.
object
Signed P50 percent change of candidate vs baseline; positive means worse.
True when diffPct is positive for the lower-is-better metric.
Baseline P95 value for the metric.
Candidate P95 value for the metric.
Headers
Section titled “Headers ”Maximum number of requests allowed per hour.
Number of requests remaining in the current window.
Unix timestamp when the rate limit window resets.
Invalid request parameters or body.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Missing or invalid API key.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Resource not found.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Rate limit exceeded.
RFC 9457 Problem Details. Served with the application/problem+json
media type. error_category, retryable, and retry_after are
Framedash extension members. type always defaults to about:blank,
so it is always present; detail and the extension members are present
only when applicable.
object
Problem type URI; about:blank when no specific type applies.
Short, human-readable summary of the problem type.
HTTP status code.
Human-readable explanation specific to this occurrence.
Extension member categorizing the error.
Extension member; true when retrying may succeed (e.g. 429, 503).
Extension member; suggested retry delay in seconds, when applicable.
Headers
Section titled “Headers ”Maximum number of requests allowed per hour.
Number of requests remaining in the current window.
Unix timestamp when the rate limit window resets.
Number of seconds to wait before retrying. Present only on 429
responses. Because the limit uses a sliding window, honor this value
per response rather than scheduling a retry for the reset time.