Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://circleci.com/api/v2
/context/{context-id}/environment-variable/{env-var-name}
Create or update an environment variable within a context. Returns information about the environment variable, not including its value.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| context-id | path | required | string | ID of the context (UUID) |
| env-var-name | path | required | string | The name of the environment variable |
application/json
ContextUpdateEnvironmentVariableRequest
| Property | Type | Required |
|---|---|---|
| value | string | required |
Error response.
The new environment variable
PUT /context/{context-id}/environment-variable/{env-var-name}
/webhook/{webhook-id}
Updates an outbound webhook.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| webhook-id | path | required | string | ID of the webhook (UUID) |
application/json
WebhookUpdateOutboundWebhookRequest
| Property | Type | Required |
|---|---|---|
| url | string | optional |
| name | string | optional |
| events | array | optional |
| verify-tls | boolean | optional |
| signing-secret | string | optional |
Error response.
A webhook
PUT /webhook/{webhook-id}
BundleDiff
{
"type": "object",
"properties": {
"created": {
"type": "array",
"items": {
"type": "string",
"description": "policy names"
}
},
"deleted": {
"type": "array",
"items": {
"type": "string",
"description": "policy names"
}
},
"modified": {
"type": "array",
"items": {
"type": "string",
"description": "policy names"
}
}
}
}
BundlePayload
{
"type": "object",
"properties": {
"policies": {
"type": "object",
"additionalProperties": {
"type": "string",
"description": "policy content"
}
}
}
}
ClaimResponse
{
"type": "object",
"required": [
"org_id"
],
"properties": {
"ttl": {
"$ref": "#/components/schemas/JSONDuration"
},
"org_id": {
"type": "string",
"format": "uuid"
},
"audience": {
"type": "array",
"items": {
"type": "string"
}
},
"project_id": {
"type": "string",
"format": "uuid"
},
"ttl_updated_at": {
"type": "string",
"format": "date-time"
},
"audience_updated_at": {
"type": "string",
"format": "date-time"
}
}
}
ContextCreateNewContextRequest
{
"type": "object",
"required": [
"name",
"owner"
],
"properties": {
"name": {
"type": "string",
"description": "The user defined name of the context."
},
"owner": {
"oneOf": [
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The unique ID of the owner of the context. Specify either this or slug."
},
"type": {
"enum": [
"account",
"organization"
],
"type": "string",
"example": "organization",
"description": "The type of the owner. Defaults to \"organization\". Accounts are only used as context owners in server."
}
}
},
{
"type": "object",
"required": [
"slug"
],
"properties": {
"slug": {
"type": "string",
"description": "A string that represents an organization. Specify either this or id. Cannot be used for accounts."
},
"type": {
"enum": [
"organization"
],
"type": "string",
"description": "The type of owner. Defaults to \"organization\". Accounts are only used as context owners in server and must be specified by an id instead of a slug."
}
}
}
]
}
}
}
ContextCreateNewContextResponse
{
"type": "object",
"title": "Context",
"required": [
"id",
"name",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The unique ID of the context."
},
"name": {
"type": "string",
"description": "The user defined name of the context."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2015-09-21T17:29:21.042Z",
"description": "The date and time the context was created."
}
}
}
ContextCreateNewContextdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
ContextCreateRestriction409Response
{
"properties": {
"message": {
"type": "string"
}
},
"additionalProperties": false
}
ContextCreateRestrictionRequest
{
"type": "object",
"properties": {
"project_id": {
"type": "string",
"format": "uuid",
"deprecated": true,
"description": "Deprecated - Use \"restriction_type\" and \"restriction_value\"\ninstead.\n\nThe project ID to use for a project restriction. This is\nmutually exclusive with restriction_type and restriction_value\nand implies restriction_type is \"project\".\n"
},
"restriction_type": {
"type": "string"
},
"restriction_value": {
"type": "string"
}
}
}
ContextCreateRestrictionResponse
{
"properties": {
"message": {
"type": "string"
}
},
"additionalProperties": false
}
ContextDeleteRestrictionResponse
{
"properties": {
"message": {
"type": "string",
"default": "restriction_id is invalid."
}
},
"additionalProperties": false
}
ContextGetInformationResponse
{
"type": "object",
"title": "Context",
"required": [
"id",
"name",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The unique ID of the context."
},
"name": {
"type": "string",
"description": "The user defined name of the context."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2015-09-21T17:29:21.042Z",
"description": "The date and time the context was created."
}
}
}
ContextGetInformationdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
ContextGetRestrictions401Response
{
"properties": {
"message": {
"type": "string"
}
},
"additionalProperties": false
}
ContextGetRestrictions404Response
{
"properties": {
"message": {
"type": "string"
}
},
"additionalProperties": false
}
ContextGetRestrictions429Response
{
"properties": {
"message": {
"type": "string",
"default": "Rate limit exceeded."
}
},
"additionalProperties": false
}
ContextGetRestrictions500Response
{
"properties": {
"message": {
"type": "string",
"default": "Internal server error."
}
},
"additionalProperties": false
}
ContextGetRestrictionsResponse
{
"properties": {
"message": {
"type": "string",
"default": "context_id is invalid."
}
},
"additionalProperties": false
}
ContextListEnvironmentVariablesResponse
{
"type": "object",
"required": [
"items",
"next_page_token"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"variable",
"created_at",
"updated_at",
"context_id"
],
"properties": {
"variable": {
"type": "string",
"example": "POSTGRES_USER",
"description": "The name of the environment variable"
},
"context_id": {
"type": "string",
"format": "uuid",
"description": "ID of the context (UUID)"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2015-09-21T17:29:21.042Z",
"description": "The date and time the environment variable was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2015-09-21T17:29:21.042Z",
"description": "The date and time the environment variable was updated"
}
}
}
},
"next_page_token": {
"type": "string",
"x-nullable": true,
"description": "A token to pass as a `page-token` query parameter to return the next page of results."
}
}
}
ContextListEnvironmentVariablesdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
ContextListOwnerContextsResponse
{
"type": "object",
"required": [
"items",
"next_page_token"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"title": "Context",
"required": [
"id",
"name",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The unique ID of the context."
},
"name": {
"type": "string",
"description": "The user defined name of the context."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2015-09-21T17:29:21.042Z",
"description": "The date and time the context was created."
}
}
}
},
"next_page_token": {
"type": "string",
"x-nullable": true,
"description": "A token to pass as a `page-token` query parameter to return the next page of results."
}
}
}
ContextListOwnerContextsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
ContextRemoveContextResponse
{
"type": "object",
"title": "MessageResponse",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "A human-readable message"
}
},
"description": "message response"
}
ContextRemoveContextdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
ContextRemoveEnvironmentVariableResponse
{
"type": "object",
"title": "MessageResponse",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "A human-readable message"
}
},
"description": "message response"
}
ContextRemoveEnvironmentVariabledefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
ContextUpdateEnvironmentVariableRequest
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "string",
"example": "some-secret-value",
"description": "The value of the environment variable"
}
}
}
ContextUpdateEnvironmentVariableResponse
{
"anyOf": [
{
"type": "object",
"required": [
"variable",
"created_at",
"updated_at",
"context_id"
],
"properties": {
"variable": {
"type": "string",
"example": "POSTGRES_USER",
"description": "The name of the environment variable"
},
"context_id": {
"type": "string",
"format": "uuid",
"description": "ID of the context (UUID)"
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2015-09-21T17:29:21.042Z",
"description": "The date and time the environment variable was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2015-09-21T17:29:21.042Z",
"description": "The date and time the environment variable was updated"
}
}
},
{
"type": "object",
"title": "MessageResponse",
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "A human-readable message"
}
},
"description": "message response"
}
]
}
ContextUpdateEnvironmentVariabledefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
Decision
{
"type": "object",
"required": [
"status"
],
"properties": {
"reason": {
"type": "string"
},
"status": {
"type": "string"
},
"enabled_rules": {
"type": "array",
"items": {
"type": "string"
}
},
"hard_failures": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Violation"
}
},
"soft_failures": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Violation"
}
}
}
}
DecisionLog
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"decision": {
"$ref": "#/components/schemas/Decision"
},
"metadata": {
"type": "object",
"properties": {
"vcs": {
"type": "object",
"properties": {
"branch": {
"type": "string"
},
"release_tag": {
"type": "string"
},
"origin_repository_url": {
"type": "string"
},
"target_repository_url": {
"type": "string"
}
}
},
"ssh_rerun": {
"type": "boolean"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"build_number": {
"type": "integer"
}
}
},
"policies": {
"type": "object",
"example": {
"policy_name1": "1f40fc92da241694750979ee6cf582f2d5d7d28e18335de05abc54d0560e0f5302860c652bf08d560252aa5e74210546f369fbbbce8c12cfc7957b2652fe9a75",
"policy_name2": "5267768822ee624d48fce15ec5ca79cbd602cb7f4c2157a516556991f22ef8c7b5ef7b18d1ff41c59370efb0858651d44a936c11b7b144c48fe04df3c6a3e8da"
},
"description": "policy-name-to-hash-map",
"additionalProperties": {
"type": "string",
"maxLength": 128,
"minLength": 128
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"time_taken_ms": {
"type": "integer"
}
}
}
DecisionSettings
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
}
}
}
InsightsGetFlakyTestsResponse
{
"type": "object",
"required": [
"flaky-tests",
"total-flaky-tests"
],
"properties": {
"flaky-tests": {
"type": "array",
"items": {
"type": "object",
"required": [
"workflow-created-at",
"classname",
"job-number",
"times-flaked",
"source",
"pipeline-number",
"file",
"workflow-name",
"job-name",
"workflow-id",
"test-name"
],
"properties": {
"file": {
"type": "string",
"x-nullable": true,
"description": "The file the test belongs to."
},
"source": {
"type": "string",
"x-nullable": true,
"description": "The source of the test."
},
"job-name": {
"type": "string",
"description": "The name of the job."
},
"classname": {
"type": "string",
"x-nullable": true,
"description": "The class the test belongs to."
},
"test-name": {
"type": "string",
"description": "The name of the test."
},
"job-number": {
"allOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "integer",
"format": "int64",
"minimum": 0
}
],
"description": "The number of the job."
},
"time-wasted": {
"allOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "integer",
"format": "int64",
"minimum": 0
}
]
},
"workflow-id": {
"description": "The ID of the workflow associated with the provided test counts"
},
"times-flaked": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of times the test flaked."
},
"workflow-name": {
"type": "string",
"description": "The name of the workflow."
},
"pipeline-number": {
"allOf": [
{
"type": "integer",
"format": "int64"
},
{
"type": "integer",
"format": "int64",
"minimum": 0
}
],
"description": "The number of the pipeline."
},
"workflow-created-at": {
"type": "string",
"description": "The date and time when workflow was created."
}
}
},
"description": "A list of all instances of flakes. Note that a test is no longer considered flaky after 2 weeks have passed without a flake. Each flake resets this timer."
},
"total-flaky-tests": {
"type": "number",
"format": "double",
"example": 5,
"description": "A count of unique tests that have failed. If your project has N tests that have flaked multiple times each, this will be equal to N."
}
},
"description": "Flaky tests response"
}
InsightsGetFlakyTestsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsGetJobTimeseriesDataResponse
{
"type": "object",
"required": [
"next_page_token",
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"min_started_at",
"max_ended_at",
"timestamp",
"metrics"
],
"properties": {
"name": {
"type": "string",
"example": "build-and-test",
"description": "The name of the workflow."
},
"metrics": {
"type": "object",
"required": [
"total_runs",
"failed_runs",
"successful_runs",
"throughput",
"median_credits_used",
"total_credits_used",
"duration_metrics"
],
"properties": {
"throughput": {
"type": "number",
"format": "float",
"description": "The average number of runs per day."
},
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"failed_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of failed runs."
},
"successful_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of successful runs."
},
"duration_metrics": {
"type": "object",
"required": [
"min",
"median",
"max",
"p95",
"total"
],
"properties": {
"max": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The max duration, in seconds, among a group of runs."
},
"min": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The minimum duration, in seconds, among a group of runs."
},
"p95": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The 95th percentile duration, in seconds, among a group of runs."
},
"total": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The total duration, in seconds, added across a group of runs."
},
"median": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The median duration, in seconds, among a group of runs."
}
},
"description": "Metrics relating to the duration of runs for a workflow."
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total credits consumed over the current timeseries interval."
},
"median_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The median credits consumed over the current timeseries interval."
}
},
"description": "Metrics relating to a workflow's runs."
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "The start of the interval for timeseries metrics."
},
"max_ended_at": {
"type": "string",
"format": "date-time",
"description": "The end time of the last execution included in the metrics."
},
"min_started_at": {
"type": "string",
"format": "date-time",
"description": "The start time for the earliest execution included in the metrics."
}
}
},
"description": "Aggregate metrics for a workflow at a time granularity"
},
"next_page_token": {
"type": "string",
"x-nullable": true,
"description": "A token to pass as a `page-token` query parameter to return the next page of results."
}
},
"description": "Project level timeseries metrics response"
}
InsightsGetJobTimeseriesDatadefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsGetProjectSummaryMetricsResponse
{
"type": "object",
"properties": {
"org_id": {
"description": "The unique ID of the organization"
},
"project_id": {
"description": "The unique ID of the project"
},
"all_branches": {
"type": "array",
"items": {
"type": "string",
"example": "main",
"description": "The VCS branch of a workflow's trigger."
},
"description": "A list of all the branches for a given project."
},
"project_data": {
"type": "object",
"required": [
"metrics",
"trends"
],
"properties": {
"trends": {
"type": "object",
"required": [
"total_runs",
"total_duration_secs",
"total_credits_used",
"success_rate",
"throughput"
],
"properties": {
"throughput": {
"type": "number",
"format": "float",
"description": "Trend value for the average number of runs per day."
},
"total_runs": {
"type": "number",
"format": "float",
"description": "The trend value for total number of runs."
},
"success_rate": {
"type": "number",
"format": "float",
"description": "The trend value for the success rate."
},
"total_credits_used": {
"type": "number",
"format": "float",
"description": "The trend value for total credits consumed."
},
"total_duration_secs": {
"type": "number",
"format": "float",
"description": "Trend value for total duration."
}
},
"description": "Metric trends aggregated across all workflows and branches for a project."
},
"metrics": {
"type": "object",
"required": [
"total_runs",
"total_duration_secs",
"total_credits_used",
"success_rate",
"throughput"
],
"properties": {
"throughput": {
"type": "number",
"format": "float",
"description": "The average number of runs per day."
},
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"success_rate": {
"type": "number",
"format": "float"
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total credits consumed over the current timeseries interval."
},
"total_duration_secs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Total duration, in seconds."
}
},
"description": "Metrics aggregated across all workflows and branches for a project."
}
},
"description": "Metrics and trends data aggregated for a given project."
},
"all_workflows": {
"type": "array",
"items": {
"type": "string",
"example": "build-and-test",
"description": "The name of the workflow."
},
"description": "A list of all the workflows for a given project."
},
"project_workflow_data": {
"type": "array",
"items": {
"type": "object",
"required": [
"workflow_name",
"metrics",
"trends"
],
"properties": {
"trends": {
"type": "object",
"required": [
"total_credits_used",
"p95_duration_secs",
"total_runs",
"success_rate"
],
"properties": {
"total_runs": {
"type": "number",
"format": "float",
"description": "The trend value for total number of runs."
},
"success_rate": {
"type": "number",
"format": "float",
"description": "The trend value for the success rate."
},
"p95_duration_secs": {
"type": "number",
"format": "float",
"description": "The 95th percentile duration among a group of workflow runs."
},
"total_credits_used": {
"type": "number",
"format": "float",
"description": "The trend value for total credits consumed."
}
},
"description": "Trends aggregated across a workflow or branch for a project."
},
"metrics": {
"type": "object",
"required": [
"total_credits_used",
"p95_duration_secs",
"total_runs",
"success_rate"
],
"properties": {
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"success_rate": {
"type": "number",
"format": "float"
},
"p95_duration_secs": {
"type": "number",
"format": "float",
"description": "The 95th percentile duration among a group of workflow runs."
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total credits consumed over the current timeseries interval."
}
},
"description": "Metrics aggregated across a workflow or branchfor a project."
},
"workflow_name": {
"type": "string",
"example": "build-and-test",
"description": "The name of the workflow."
}
}
},
"description": "A list of metrics and trends data for workflows for a given project."
},
"project_workflow_branch_data": {
"type": "array",
"items": {
"type": "object",
"required": [
"workflow_name",
"branch",
"metrics",
"trends"
],
"properties": {
"branch": {
"type": "string",
"example": "main",
"description": "The VCS branch of a workflow's trigger."
},
"trends": {
"type": "object",
"required": [
"total_credits_used",
"p95_duration_secs",
"total_runs",
"success_rate"
],
"properties": {
"total_runs": {
"type": "number",
"format": "float",
"description": "The trend value for total number of runs."
},
"success_rate": {
"type": "number",
"format": "float",
"description": "The trend value for the success rate."
},
"p95_duration_secs": {
"type": "number",
"format": "float",
"description": "The 95th percentile duration among a group of workflow runs."
},
"total_credits_used": {
"type": "number",
"format": "float",
"description": "The trend value for total credits consumed."
}
},
"description": "Trends aggregated across a workflow or branch for a project."
},
"metrics": {
"type": "object",
"required": [
"total_credits_used",
"p95_duration_secs",
"total_runs",
"success_rate"
],
"properties": {
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"success_rate": {
"type": "number",
"format": "float"
},
"p95_duration_secs": {
"type": "number",
"format": "float",
"description": "The 95th percentile duration among a group of workflow runs."
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total credits consumed over the current timeseries interval."
}
},
"description": "Metrics aggregated across a workflow or branchfor a project."
},
"workflow_name": {
"type": "string",
"example": "build-and-test",
"description": "The name of the workflow."
}
}
},
"description": "A list of metrics and trends data for branches for a given project."
}
}
}
InsightsGetProjectSummaryMetricsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsGetProjectWorkflowJobMetricsResponse
{
"type": "object",
"required": [
"items",
"next_page_token"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"metrics",
"window_start",
"window_end"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the job."
},
"metrics": {
"type": "object",
"required": [
"total_runs",
"failed_runs",
"successful_runs",
"duration_metrics",
"success_rate",
"total_credits_used",
"throughput"
],
"properties": {
"throughput": {
"type": "number",
"format": "float",
"description": "The average number of runs per day."
},
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"failed_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of failed runs."
},
"success_rate": {
"type": "number",
"format": "float"
},
"successful_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of successful runs."
},
"duration_metrics": {
"type": "object",
"required": [
"min",
"mean",
"median",
"p95",
"max",
"standard_deviation"
],
"properties": {
"max": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The max duration, in seconds, among a group of runs."
},
"min": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The minimum duration, in seconds, among a group of runs."
},
"p95": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The 95th percentile duration, in seconds, among a group of runs."
},
"mean": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The mean duration, in seconds, among a group of runs."
},
"median": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The median duration, in seconds, among a group of runs."
},
"standard_deviation": {
"type": "number",
"format": "float",
"x-nullable": true,
"description": "The standard deviation, in seconds, among a group of runs."
}
},
"description": "Metrics relating to the duration of runs for a workflow job."
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total credits consumed by the job in the aggregation window. Note that Insights is not a real time financial reporting tool and should not be used for credit reporting."
}
},
"description": "Metrics relating to a workflow job's runs."
},
"window_end": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the last build within the requested reporting window."
},
"window_start": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the first build within the requested reporting window."
}
}
},
"description": "Job summary metrics."
},
"next_page_token": {
"type": "string",
"x-nullable": true,
"description": "A token to pass as a `page-token` query parameter to return the next page of results."
}
},
"description": "Paginated workflow job summary metrics."
}
InsightsGetProjectWorkflowJobMetricsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsGetProjectWorkflowMetricsResponse
{
"type": "object",
"required": [
"items",
"next_page_token"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"metrics",
"window_start",
"window_end",
"project_id"
],
"properties": {
"name": {
"type": "string",
"example": "build-and-test",
"description": "The name of the workflow."
},
"metrics": {
"type": "object",
"required": [
"total_runs",
"successful_runs",
"mttr",
"total_credits_used",
"failed_runs",
"success_rate",
"duration_metrics",
"total_recoveries",
"throughput"
],
"properties": {
"mttr": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The mean time to recovery (mean time between failures and their next success) in seconds."
},
"throughput": {
"type": "number",
"format": "float",
"description": "The average number of runs per day."
},
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"failed_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of failed runs."
},
"success_rate": {
"type": "number",
"format": "float"
},
"successful_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of successful runs."
},
"duration_metrics": {
"type": "object",
"required": [
"min",
"mean",
"median",
"p95",
"max",
"standard_deviation"
],
"properties": {
"max": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The max duration, in seconds, among a group of runs."
},
"min": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The minimum duration, in seconds, among a group of runs."
},
"p95": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The 95th percentile duration, in seconds, among a group of runs."
},
"mean": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The mean duration, in seconds, among a group of runs."
},
"median": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The median duration, in seconds, among a group of runs."
},
"standard_deviation": {
"type": "number",
"format": "float",
"x-nullable": true,
"description": "The standard deviation, in seconds, among a group of runs."
}
},
"description": "Metrics relating to the duration of runs for a workflow."
},
"total_recoveries": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The number of recovered workflow executions per day."
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The total credits consumed by the workflow in the aggregation window. Note that Insights is not a real time financial reporting tool and should not be used for credit reporting."
}
},
"description": "Metrics relating to a workflow's runs."
},
"project_id": {
"description": "The unique ID of the project"
},
"window_end": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the last build within the requested reporting window."
},
"window_start": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the first build within the requested reporting window."
}
}
},
"description": "Workflow summary metrics."
},
"next_page_token": {
"type": "string",
"x-nullable": true,
"description": "A token to pass as a `page-token` query parameter to return the next page of results."
}
},
"description": "Paginated workflow summary metrics."
}
InsightsGetProjectWorkflowMetricsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsGetProjectWorkflowTestMetricsResponse
{
"type": "object",
"required": [
"average_test_count",
"most_failed_tests",
"most_failed_tests_extra",
"slowest_tests",
"slowest_tests_extra",
"total_test_runs",
"test_runs"
],
"properties": {
"test_runs": {
"type": "array",
"items": {
"type": "object",
"required": [
"pipeline_number",
"workflow_id",
"success_rate",
"test_counts"
],
"properties": {
"test_counts": {
"type": "object",
"required": [
"error",
"failure",
"skipped",
"success",
"total"
],
"properties": {
"error": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of tests with the error status"
},
"total": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of tests"
},
"failure": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of tests with the failure status"
},
"skipped": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of tests with the skipped status"
},
"success": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of tests with the success status"
}
},
"description": "Test counts for a given pipeline number"
},
"workflow_id": {
"description": "The ID of the workflow associated with the provided test counts"
},
"success_rate": {
"type": "number",
"format": "float",
"description": "The success rate calculated from test counts"
},
"pipeline_number": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of the pipeline associated with the provided test counts"
}
}
},
"description": "Test counts grouped by pipeline number and workflow id"
},
"slowest_tests": {
"type": "array",
"items": {
"type": "object",
"required": [
"failed_runs",
"job_name",
"p95_duration",
"test_name",
"file",
"source",
"classname",
"total_runs",
"flaky"
],
"properties": {
"file": {
"type": "string",
"x-nullable": true,
"description": "The file the test belongs to."
},
"flaky": {
"type": "boolean",
"description": "Whether the test is flaky."
},
"source": {
"type": "string",
"x-nullable": true,
"description": "The source of the test."
},
"job_name": {
"type": "string",
"description": "The name of the job."
},
"classname": {
"type": "string",
"x-nullable": true,
"description": "The class the test belongs to."
},
"test_name": {
"type": "string",
"description": "The name of the test."
},
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of times the test was run."
},
"failed_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of times the test failed"
},
"p95_duration": {
"type": "number",
"format": "double",
"x-nullable": true,
"description": "The 95th percentile duration, in seconds, among a group of test runs."
}
}
},
"description": "Metrics for the slowest running tests"
},
"total_test_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of test runs"
},
"most_failed_tests": {
"type": "array",
"items": {
"type": "object",
"required": [
"failed_runs",
"job_name",
"p95_duration",
"test_name",
"file",
"source",
"classname",
"total_runs",
"flaky"
],
"properties": {
"file": {
"type": "string",
"x-nullable": true,
"description": "The file the test belongs to."
},
"flaky": {
"type": "boolean",
"description": "Whether the test is flaky."
},
"source": {
"type": "string",
"x-nullable": true,
"description": "The source of the test."
},
"job_name": {
"type": "string",
"description": "The name of the job."
},
"classname": {
"type": "string",
"x-nullable": true,
"description": "The class the test belongs to."
},
"test_name": {
"type": "string",
"description": "The name of the test."
},
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of times the test was run."
},
"failed_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of times the test failed"
},
"p95_duration": {
"type": "number",
"format": "double",
"x-nullable": true,
"description": "The 95th percentile duration, in seconds, among a group of test runs."
}
}
},
"description": "Metrics for the most frequently failing tests"
},
"average_test_count": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The average number of tests executed per run"
},
"slowest_tests_extra": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of tests with the same duration rate being omitted from slowest_tests"
},
"most_failed_tests_extra": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of tests with the same success rate being omitted from most_failed_tests"
}
},
"description": "Project level test metrics response"
}
InsightsGetProjectWorkflowTestMetricsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsGetRecentWorkflowRunsResponse
{
"type": "object",
"required": [
"items",
"next_page_token"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"branch",
"duration",
"created_at",
"stopped_at",
"credits_used",
"status",
"is_approval"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The unique ID of the workflow."
},
"branch": {
"type": "string",
"example": "main",
"description": "The VCS branch of a Workflow's trigger."
},
"status": {
"enum": [
"success",
"failed",
"error",
"canceled",
"unauthorized"
],
"type": "string",
"x-nullable": true,
"description": "Workflow status."
},
"duration": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The duration in seconds of a run."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "The date and time the workflow was created."
},
"stopped_at": {
"type": "string",
"format": "date-time",
"x-nullable": true,
"description": "The date and time the workflow stopped."
},
"is_approval": {
"type": "boolean",
"example": false,
"description": "Describes if the job is an approval job or not. Approval jobs are intermediary jobs that are created to pause the workflow until approved."
},
"credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of credits used during execution. Note that Insights is not a real time financial reporting tool and should not be used for credit reporting."
}
}
},
"description": "Recent workflow runs."
},
"next_page_token": {
"type": "string",
"x-nullable": true,
"description": "A token to pass as a `page-token` query parameter to return the next page of results."
}
},
"description": "Paginated recent workflow runs."
}
InsightsGetRecentWorkflowRunsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsGetSummaryMetricsWithTrendsResponse
{
"type": "object",
"required": [
"org_data",
"org_project_data",
"all_projects"
],
"properties": {
"org_data": {
"type": "object",
"required": [
"metrics",
"trends"
],
"properties": {
"trends": {
"type": "object",
"required": [
"total_runs",
"total_duration_secs",
"total_credits_used",
"success_rate",
"throughput"
],
"properties": {
"throughput": {
"type": "number",
"format": "float",
"description": "Trend value for the average number of runs per day."
},
"total_runs": {
"type": "number",
"format": "float",
"description": "The trend value for total number of runs."
},
"success_rate": {
"type": "number",
"format": "float",
"description": "The trend value for the success rate."
},
"total_credits_used": {
"type": "number",
"format": "float",
"description": "The trend value for total credits consumed."
},
"total_duration_secs": {
"type": "number",
"format": "float",
"description": "Trend value for total duration."
}
},
"description": "Trends for a single org."
},
"metrics": {
"type": "object",
"required": [
"total_runs",
"total_duration_secs",
"total_credits_used",
"success_rate",
"throughput"
],
"properties": {
"throughput": {
"type": "number",
"format": "float",
"description": "The average number of runs per day."
},
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"success_rate": {
"type": "number",
"format": "float"
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total credits consumed over the current timeseries interval."
},
"total_duration_secs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Total duration, in seconds."
}
},
"description": "Metrics for a single org metrics."
}
},
"description": "Aggregated metrics for an org, with trends."
},
"all_projects": {
"type": "array",
"items": {
"type": "string"
},
"x-nullable": true,
"description": "A list of all the project names in the organization."
},
"org_project_data": {
"type": "array",
"items": {
"type": "object",
"required": [
"project_name",
"metrics",
"trends"
],
"properties": {
"trends": {
"type": "object",
"required": [
"total_credits_used",
"total_duration_secs",
"total_runs",
"success_rate"
],
"properties": {
"total_runs": {
"type": "number",
"format": "float",
"description": "The trend value for total number of runs."
},
"success_rate": {
"type": "number",
"format": "float",
"description": "The trend value for the success rate."
},
"total_credits_used": {
"type": "number",
"format": "float",
"description": "The trend value for total credits consumed."
},
"total_duration_secs": {
"type": "number",
"format": "float",
"description": "Trend value for total duration."
}
},
"description": "Trends for a single project, across all branches."
},
"metrics": {
"type": "object",
"required": [
"total_credits_used",
"total_duration_secs",
"total_runs",
"success_rate"
],
"properties": {
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"success_rate": {
"type": "number",
"format": "float"
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total credits consumed over the current timeseries interval."
},
"total_duration_secs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Total duration, in seconds."
}
},
"description": "Metrics for a single project, across all branches."
},
"project_name": {
"type": "string",
"example": "api-preview-docs",
"description": "The name of the project."
}
}
},
"description": "Metrics for a single project, across all branches"
}
},
"description": "Summary metrics with trends for the entire org, and for each project."
}
InsightsGetSummaryMetricsWithTrendsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsGetWorkflowSummaryMetricsResponse
{
"type": "object",
"required": [
"metrics",
"trends",
"workflow_names"
],
"properties": {
"trends": {
"type": "object",
"required": [
"total_runs",
"failed_runs",
"success_rate",
"p95_duration_secs",
"median_duration_secs",
"total_credits_used",
"mttr",
"throughput"
],
"properties": {
"mttr": {
"type": "number",
"format": "float",
"description": "trend for mean time to recovery (mean time between failures and their next success)."
},
"throughput": {
"type": "number",
"format": "float",
"description": "Trend value for the average number of runs per day."
},
"total_runs": {
"type": "number",
"format": "float",
"description": "The trend value for total number of runs."
},
"failed_runs": {
"type": "number",
"format": "float",
"description": "The trend value for number of failed runs."
},
"success_rate": {
"type": "number",
"format": "float",
"description": "The trend value for the success rate."
},
"p95_duration_secs": {
"type": "number",
"format": "float",
"description": "Trend value for the 95th percentile duration for a workflow for a given time window."
},
"total_credits_used": {
"type": "number",
"format": "float",
"description": "The trend value for total credits consumed."
},
"median_duration_secs": {
"type": "number",
"format": "float",
"description": "Trend value for the 50th percentile duration for a workflow for a given time window."
}
},
"description": "Trends for aggregated metrics across a workflow for a given time window."
},
"metrics": {
"type": "object",
"required": [
"total_runs",
"successful_runs",
"mttr",
"total_credits_used",
"failed_runs",
"success_rate",
"window_start",
"duration_metrics",
"window_end",
"throughput",
"completed_runs"
],
"properties": {
"mttr": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The mean time to recovery (mean time between failures and their next success) in seconds."
},
"throughput": {
"type": "number",
"format": "float",
"description": "The average number of runs per day."
},
"total_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The total number of runs, including runs that are still on-hold or running."
},
"window_end": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the last build within the requested reporting window."
},
"failed_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of failed runs."
},
"success_rate": {
"type": "number",
"format": "float"
},
"window_start": {
"type": "string",
"format": "date-time",
"description": "The timestamp of the first build within the requested reporting window."
},
"completed_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The number of runs that ran to completion within the aggregation window"
},
"successful_runs": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "The number of successful runs."
},
"duration_metrics": {
"type": "object",
"required": [
"min",
"mean",
"median",
"p95",
"max",
"standard_deviation"
],
"properties": {
"max": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The max duration, in seconds, among a group of runs."
},
"min": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The minimum duration, in seconds, among a group of runs."
},
"p95": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The 95th percentile duration, in seconds, among a group of runs."
},
"mean": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The mean duration, in seconds, among a group of runs."
},
"median": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The median duration, in seconds, among a group of runs."
},
"standard_deviation": {
"type": "number",
"format": "float",
"x-nullable": true,
"description": "The standard deviation, in seconds, among a group of runs."
}
},
"description": "Metrics relating to the duration of runs for a workflow."
},
"total_credits_used": {
"type": "integer",
"format": "int64",
"minimum": 0,
"x-nullable": true,
"description": "The total credits consumed by the workflow in the aggregation window. Note that Insights is not a real time financial reporting tool and should not be used for credit reporting."
}
},
"description": "Metrics aggregated across a workflow for a given time window."
},
"workflow_names": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of all the workflow names for a given project."
}
},
"description": "Workflow level aggregated metrics and trends response"
}
InsightsGetWorkflowSummaryMetricsdefaultResponse
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
InsightsListProjectBranchesResponse
{
"type": "object",
"required": [
"org_id",
"project_id",
"branches"
],
"properties": {
"org_id": {
"description": "The unique ID of the organization"
},
"branches": {
"type": "array",
"items": {
"type": "string",
"example": "main",
"description": "The VCS branch of a workflow's trigger."
},
"description": "A list of all the branches for a given project."
},
"project_id": {
"description": "The unique ID of the project"
}
},
"description": "Project branches response."
}
| Version | Endpoints | Schemas | Ingested | Status |
|---|---|---|---|---|
| v2 | 78 | 169 | 2026-05-11 | current |
| v2 | 78 | 169 | 2026-04-16 |