Get a build

OpenAPI contract

Method

GET

Path

/api/v1/builds/{taskId}

Security

jwtBearer (bearer) OR automationKey (bearer)

Response status

200 400 401 403 404 429 500

Request and response schemas

JSON

{
  "requestBody": {},
  "responses": {
    "200": {
      "description": "Build",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/CompileTaskResponse"
        }
      }
    },
    "400": {
      "description": "Invalid request",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RequestError"
        }
      }
    },
    "401": {
      "description": "Authentication required or invalid",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "403": {
      "description": "Authenticated but not permitted",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/SecurityError"
        }
      }
    },
    "404": {
      "description": "Requested build was not found",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    },
    "429": {
      "description": "HTTP rate limit or API-key NCU usage limit exceeded",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/RateLimitError"
        }
      }
    },
    "500": {
      "description": "Unexpected server error",
      "content": {
        "application/json": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

Read one build or draft with a JWT or an nfy_ key carrying build:read. For a project task, the caller must have effective build:read capability on that project; a legacy or ad-hoc task uses its exact-owner fallback. The task representation exposes lifecycle, progress, error information, generated URLs, hosting path, resolved configuration, and output metadata when available. A task outside that resource boundary is not exposed.

For an accepted submission or started draft, follow the returned status URL and honor its retry guidance before the next poll. GET is the safe retry surface: transient read failures can be retried, whereas resubmitting a POST may create a second build. Stop polling on terminal success, failure, or cancellation; only download after output is available.