This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/dws-processor/tools-and-api/analyze-build-api.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Analyze Build API

Use the analyze Build API to estimate the cost of a Build API request without executing the workflow. The /analyze_build endpoint validates and analyzes Build API instructions and returns the estimated cost and required features.

The analysis request is free of charge. Use it before running large, batch, or expensive workflows such as optical character recognition (OCR), PDF/UA, Office conversion, or multistep processing.

Analyze a Build API request

The following example estimates the cost of converting a remote PDF to DOCX.

curl -X POST https://api.nutrient.io/analyze_build \
-H "Authorization: Bearer $NUTRIENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"parts": [
{
"file": {
"url": "https://example.com/document.pdf"
},
"content_type": "application/pdf"
}
],
"output": {
"type": "docx"
}
}'

Analyze OCR cost

OCR can have different cost implications depending on page count and workflow configuration. Analyze OCR requests before running them over large document batches.

Use this instructions object to analyze OCR cost:

{
"parts": [
{
"file": {
"url": "https://example.com/scanned-document.pdf"
},
"content_type": "application/pdf"
}
],
"actions": [
{
"type": "ocr",
"language": "english"
}
]
}

Analyze PDF/UA cost

PDF/UA auto-tagging is a page-based compliance workflow. Use /analyze_build to estimate the cost before processing large documents.

Use this instructions object to analyze PDF/UA cost:

{
"parts": [
{
"file": {
"url": "https://example.com/document.pdf"
},
"content_type": "application/pdf"
}
],
"output": {
"type": "pdfua"
}
}

Analyze multistep workflows

You can analyze the same Build API instructions you plan to send to /build. The following example estimates a workflow that merges two PDFs, applies OCR, adds a watermark, and linearizes the output.

Use this instructions object to analyze a multistep workflow:

{
"parts": [
{
"file": {
"url": "https://example.com/part-1.pdf"
},
"content_type": "application/pdf"
},
{
"file": {
"url": "https://example.com/part-2.pdf"
},
"content_type": "application/pdf"
}
],
"actions": [
{
"type": "ocr",
"language": "english"
},
{
"type": "watermark",
"text": "ARCHIVE",
"width": "50%",
"height": "20%",
"opacity": 0.3,
"rotation": 45
}
],
"output": {
"type": "pdf",
"optimize": {
"linearize": true
}
}
}

Provide content types for remote files

When you analyze requests with remote files, include content_type for each file when possible. This helps the endpoint identify conversion features accurately, especially for Office, image, email, AutoCAD, and PDF inputs.

Use this structure to provide a content type for a remote file:

{
"parts": [
{
"file": {
"url": "https://example.com/report.docx"
},
"content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
}
]
}

Without content_type, analysis may not correctly identify some conversion features.

Understand the response

The response includes a billing object with the estimated cost in US dollars and a breakdown of the operations the request uses.

The following example shows an analysis response:

{
"billing": {
"currency": "USD",
"estimatedCost": "0.0375",
"components": [
{
"product": "processor",
"operation": "annotations",
"unit": "use",
"quantity": 1,
"unitPrice": "0.0375",
"cost": "0.0375"
}
]
}
}

Response fields:

FieldDescription
currencyCurrency of all amounts in the response. Always USD.
estimatedCostTotal estimated cost if the request is executed, as a decimal string.
componentsBreakdown of the operations required by the request.
components[].productProduct the operation belongs to, such as processor.
components[].operationOperation the request uses, such as annotations or ocr.
components[].unitBilling unit for the operation, such as use or page.
components[].quantityNumber of units the request uses.
components[].unitPricePrice per unit, as a decimal string.
components[].costEstimated cost for that operation, as a decimal string.

Amounts are decimal strings so they keep their precision. Parse them with a decimal type rather than a floating-point number.

Operations priced per page can’t be fully estimated before the output exists, because the page count isn’t known yet. For those components, the response includes unitPrice, but quantity and cost are null, and estimatedCost is null for the whole request. Multiply unitPrice by the page count you expect to get an estimate.

Accounts still on a credits plan get the earlier response instead, with cost, unit_cost, and units in credits and a required_features breakdown with usage paths to the instructions that triggered each feature.

Analyze before batch processing

For batch workflows, analyze a representative request before processing the full batch. This helps you:

  • Estimate the total cost.
  • Detect unexpectedly expensive workflow steps.
  • Confirm that the request uses the expected features.
  • Decide whether to split large jobs into smaller requests.
  • Check whether OCR, PDF/UA, Office conversion, or optimization settings are needed.

The analysis result is an estimate for the provided instructions. Actual execution can still fail if a remote file is unavailable, a document is password-protected, the input content is invalid, or the output exceeds limits.

Compare analyze and build

Use /analyze_build when you want to estimate cost and required features without producing a document.

Use /build when you want to execute the workflow and receive the processed output file.

EndpointExecutes workflowReturns documentCharges usage
/analyze_buildNoNoNo
/buildYesYesYes

Check your account balance

To check your available balance, use the account endpoints in the API reference. You can combine balance checks with /analyze_build to decide whether to run a large workflow.

Run this request to check account information:

Terminal window
curl -X GET https://api.nutrient.io/account/info \
-H "Authorization: Bearer $NUTRIENT_API_KEY"

Reference

Analyze Build uses the same BuildInstructions structure as /build, but it only accepts JSON instructions and doesn’t upload or process local files:

type AnalyzeBuildRequest = BuildInstructions;
type AnalyzeBuildResponse = {
billing: {
currency: "USD",
estimatedCost: string | null,
components: Array<{
product: string,
operation: string,
unit: string,
quantity: number | null,
unitPrice: string,
cost: string | null,
}>,
},
};
type BuildInstructions = {
parts: Part[],
actions?: BuildAction[],
output?: BuildOutput,
};