---
title: "Refine a run until on-brand, within budget"
method: POST
path: "/runs/{runId}/refine-to-brand"
tags: ["Runs"]
---

# Refine a run until on-brand, within budget

`POST /runs/{runId}/refine-to-brand`

## Request

- Base URL: `https://app.uselamina.ai/v1`
- URL: `https://app.uselamina.ai/v1/runs/{runId}/refine-to-brand`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Bounded generate → score → refine loop. Repeats score → refine (re-rolling with the specific deviations fed back in) on a completed run and stops the instant brandFit >= minScore, iterations >= maxIterations, or the credit budget would be exceeded — whichever first. Returns the best result and exactly how many iterations and credits it took. The credit cap is never exceeded.

## Path parameters

- `runId` string, uuid, required

## Request body

- object
  - `minScore` number: Target brand-fit score to stop at (default 80).
  - `maxIterations` integer: Most refine passes to try (default 3).
  - `maxCredits` number: Hard credit ceiling — never exceeded (default 200).
  - `brandProfileId` string: Brand to score against. Defaults to the run's workflow brand.

## Response `200`

Refine loop result

- object
  - `data` object, required
    - `runId` string, required
    - `brandProfileId` string
    - `minScore` number
    - `maxCredits` number
    - `iterations` integer, required: Refine passes performed.
    - `creditsSpent` number, required
    - `stoppedBecause` 'met_score' | 'max_iterations' | 'budget' | 'no_output', required
    - `summary` string: Human-readable spend-vs-budget, attempts, and best-score line.
    - `best` object, required
      - `iteration` integer
      - `brandFit` number, nullable
      - `imageUrl` string
    - `attempts` object[]
      - `iteration` integer
      - `brandFit` number, nullable
      - `imageUrl` string
      - `creditsSpent` number
      - `cumulativeCredits` number
      - `deviations` string[]

## Other responses

- `401`: Missing or invalid API key
- `500`: Internal server error

---

[API](https://skmtc.dev/uselamina/apis/lamina-v1-api.md) · [All operations](https://skmtc.dev/uselamina/apis/lamina-v1-api/llms.txt) · [OpenAPI document](https://skmtc.dev/uselamina/apis/lamina-v1-api/revisions/73b598526531?raw)