Analyze Build API

Use the analyze Build API to estimate the credit 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.1
Host: api.nutrient.io
Authorization: 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 credit 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 the total estimated cost and a breakdown of required features.

The following example shows an analysis response:

{
  "cost": 3.5,
  "required_features": {
    "ocr_api": [
      {
        "unit_cost": 2,
        "unit_type": "per_use",
        "units": 1,
        "cost": 2,
        "usage": ["$.actions[0]"]
      }
    ],
    "document_editor_api": [
      {
        "unit_cost": 1,
        "unit_type": "per_use",
        "units": 1,
        "cost": 1,
        "usage": ["$.parts"]
      }
    ]
  }
}

Response fields:

Use the usage paths to identify which parts of your instructions contribute to the estimated cost.

Analyze before batch processing

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

• Estimate total credit usage.
• 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.

Check account credits

To check your available credits, use the account or credits endpoints in the API reference. You can combine credit 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 = {
  cost?: number,
  required_features?: Record<
    string,
    Array<{
      unit_cost: number,
      unit_type: "per_use" | "per_output_page",
      units: number,
      cost: number,
      usage: string[],
    }>
  >,
};

type BuildInstructions = {
  parts: Part[],
  actions?: BuildAction[],
  output?: BuildOutput,
};

Related API reference operations

• Refer to the analyze a build request endpoint API reference to estimate Build API credit usage 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 available credits.

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.