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" } }'POST /analyze_build HTTP/1.1Host: api.nutrient.ioAuthorization: Bearer <your_api_key_here>Content-Type: application/json
{ "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:
| Field | Description |
|---|---|
currency | Currency of all amounts in the response. Always USD. |
estimatedCost | Total estimated cost if the request is executed, as a decimal string. |
components | Breakdown of the operations required by the request. |
components[].product | Product the operation belongs to, such as processor. |
components[].operation | Operation the request uses, such as annotations or ocr. |
components[].unit | Billing unit for the operation, such as use or page. |
components[].quantity | Number of units the request uses. |
components[].unitPrice | Price per unit, as a decimal string. |
components[].cost | Estimated 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.
| Endpoint | Executes workflow | Returns document | Charges usage |
|---|---|---|---|
/analyze_build | No | No | No |
/build | Yes | Yes | Yes |
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:
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,};Related API reference operations
- Refer to the analyze a build request endpoint API reference to estimate the cost of a Build API request without executing the workflow.
- Refer to the build document endpoint API reference to execute the workflow and return the processed output.
- Refer to the get account information endpoint API reference to check account information and your available balance.
Related guides
- Refer to the Build API workflows guide.
- Refer to the PDF OCR API guide.
- Refer to the PDF/UA auto-tagging API guide.
- Refer to the Office-to-PDF API guide.
- Refer to the PDF-to-Office API guide.
- Refer to the PDF optimization API guide.
- Refer to the tools and APIs guide.