> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylon.mortgage/llms.txt
> Use this file to discover all available pages before exploring further.

# Most optimal structure

> Get the single best loan structure for your objective (e.g. `MIN_PITIA` or `MIN_DOWN_PAYMENT`), with optional per-product breakdown.

When you want the **one best structure** for a borrower's objective - without building or scanning a full rate sheet - use **calculate optimal structure**. The API runs the optimizer and returns the best result (e.g., minimum [PITIA](/entity-models/key-concepts/piti) or minimum down payment) across all products and structures. Optionally, use **Product Breakdown** to see the best structure **per product** for that same objective.

## How it works

<Steps>
  <Step title="Submit the job">
    Call the <code>calculateOptimalStructure</code> mutation with the loan ID, objective, and optional constraints.
  </Step>

  <Step title="Poll for completion">
    Query <code>optimalStructure(id)</code> with the job ID until <code>status</code> indicates completion.
  </Step>

  <Step title="Use the result">
    Read <code>result</code> for the single best structure across all products. Use <code>productBreakdown</code> for the best structure per product.
  </Step>
</Steps>

For **optimization objectives** (`MIN_PITIA`, `MIN_OUT_OF_POCKET`, `MIN_DOWN_PAYMENT`) and **pricing constraints**, see [Overview - Optimization objectives](/guides/getting-started/pricing-optimizations/overview#optimization-objectives) and [Borrower preferences and pricing constraints](/guides/getting-started/pricing-optimizations/overview#borrower-preferences-and-pricing-constraints).

***

## Performance and response time

Most optimal structure is **asynchronous**: you submit the job, then poll until complete. It is **much faster** than the [full rate sheet](/guides/getting-started/pricing-optimizations/full-rate-sheet), which evaluates the entire rate stack across all products. Response times are typically **about 3 seconds**, compared to 10-20 seconds for the full rate sheet. Use most optimal structure when you only need the single best structure and want quicker response times.

### UI/UX recommendations

* **Show a loading state** - Display a loading indicator while the asynchronous job completes and you poll for the result. A short message like "Finding your best option..." is sufficient; 3 seconds usually doesn't require the longer copy used for the full rate sheet.
* **Avoid repeated calls** - Cache or reuse the result until the user or loan data changes (e.g. loan data, [borrower preferences](/guides/getting-started/pricing-optimizations/overview#borrower-preferences-and-pricing-constraints), or objective). Don't refetch on every tab focus or minor UI interaction.

***

## 1. Start the calculation (mutation)

```graphql theme={null}
mutation calculateOptimalStructure($input: CalculateOptimalStructureInput!) {
  pricing {
    calculateOptimalStructure(input: $input) {
      job {
        id
        status
      }
    }
  }
}
```

**Variables example:**

```json theme={null}
{
  "input": {
    "loanId": "app_5ap9raB5XUhQZLLkpg31Ve",
    "objectiveIntent": "MIN_DOWN_PAYMENT",
    "pricingConstraints": {
      "maxLtv": 0.90
    }
  }
}
```

For fixed LTV structures (e.g. 90% LTV) using `MIN_DOWN_PAYMENT` and `maxLtv`, see [Fixed loan structures](/guides/getting-started/pricing-optimizations/fixed-loan-structures).

## 2. Get the result (query)

Poll **`pricing.optimalStructure(id)`** with the job `id` until `status` is complete, then read **`result`** and optionally **`productBreakdown`**.

```graphql theme={null}
query getOptimalStructure($id: ID!) {
  pricing {
    optimalStructure(id: $id) {
      id
      status
      result {
        id
        apr
        rate
        closingCosts
        monthlyPayment
        downPaymentAmount
        principal
        cashFromToBorrower
        cashOutAmount
        cashOutType
        concessionPoints
        dti
        floodInsurance
        interest
        loanTermYears
        lock
        ltv
        mortgageInsurance
        totalCost
        totalPoints
        apor {
          rate
        }
        pitia {
          floodInsurance
          hoaDues
          homeownersInsurance
          mortgageInsurance
          principalAndInterest
          taxes
        }
        product {
          id
          description
          type
        }
      }
      productBreakdown {
        ... on EligibleProductStructure {
          rate
          apr
          monthlyPayment
          downPaymentAmount
          product { id description type }
        }
        ... on IneligibleProductStructure {
          rate
          product { id description type }
          ineligibilityDetails { __typename }
        }
        ... on StructuringError {
          rate
          product { id description type }
          unsatisfiabilityDetails { __typename }
        }
      }
    }
  }
}
```

## Result vs Product Breakdown

| Field                  | Description                                                                                                                                                                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`result`**           | The **single best structure** for the loan for your objective (e.g., the structure with `MIN_PITIA` across all products and structures). Use this when you only need "the answer."                                                                          |
| **`productBreakdown`** | The **best structure per product** for the same objective. Each item is a **`StructuringResult`** (eligible, ineligible, or error). See [Overview - Pricing response types](/guides/getting-started/pricing-optimizations/overview#pricing-response-types). |

<Info>
  **Polling**: <code>optimalStructure</code> is a job. Poll on <code>status</code> (e.g. <code>COMPLETED</code>, <code>FAILED</code>) and only read <code>result</code> / <code>productBreakdown</code> when the job has finished.
</Info>

## Related

* [Full rate sheet optimizations](/guides/getting-started/pricing-optimizations/full-rate-sheet)  -  Full rate stack across all products and structures, with eligible and ineligible options and their reasons.
* [Pricing optimizations (Overview)](/guides/getting-started/pricing-optimizations/overview)  -  Optimization objectives, constraints, and pricing response types.