> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.morphiaone.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.morphiaone.ai/_mcp/server.

# Read the caller's credit balance

GET https://api.morphiaone.ai/v1/credits/balance

The credit balance of the account that owns the API key, in abstract units (never
money); the answer carries no account identifier. `spendable_units` is what a
new submission may spend (units funded by test payments are excluded while
`enforced`), `enforced` says whether a submission without the units is refused
`402 INSUFFICIENT_CREDITS`, and `unit_costs` is what one accepted job of each
operation costs. Served only where the balance endpoint is enabled for your
account. A ledger that cannot be read is a 503, never a zero balance.

Reference: https://docs.morphiaone.ai/api-reference/endpoints/credits/get-balance

## Authentication

- `X-API-Key` header (required) — API key for one environment of your account. Keep server-side; never expose in browser clients.

## Response

### 200

Successful Response

- `as_of` (datetime, required) — When the balance was read (UTC).
- `available_units` (integer, required) — Settled minus held, the ledger's available units. May be negative after an adjustment.
- `enforced` (boolean, required) — True when a submission without the units is refused `402 INSUFFICIENT_CREDITS`.
- `held_units` (integer, required) — Units held by accepted, unsettled jobs.
- `low_balance` (boolean, required) — True when a low-balance threshold is configured and `spendable_units` is at or below it.
- `settled_units` (integer, required) — Grants and adjustments minus captured charges.
- `spendable_units` (integer, required) — Units a new submission may spend: `available_units`, minus `test_funded_units` when `enforced` is true.
- `test_funded_units` (integer, required) — Units funded by test payments. Not spendable while `enforced` is true.
- `unit_costs` (map from string to integer, required) — Units one accepted job of each operation costs.
- `object` (string, optional, default: credit_balance) — Always `credit_balance`.

## Errors

### 401 Unauthorized Error

Missing or invalid API key

- `error` (ErrorDetail, required)

### 403 Forbidden Error

API key is not allowed from this network

- `error` (ErrorDetail, required)

### 503 Service Unavailable Error

Credit ledger unavailable

- `error` (ErrorDetail, required)

## Types

### ErrorDetail

- `code` (string, required)
- `message` (string, required)
- `request_id` (string, required)
- `details` (ErrorDetailDetails, optional)
- `doc_url` (string, optional, nullable)
- `retryable` (boolean, optional, nullable)

### ErrorDetailDetails

## Examples

**Response**

```json
{
  "as_of": "2026-10-03T10:00:00Z",
  "available_units": 42,
  "enforced": true,
  "held_units": 3,
  "low_balance": false,
  "settled_units": 45,
  "spendable_units": 42,
  "test_funded_units": 0,
  "unit_costs": {
    "hair.try_on": 1,
    "makeup.apply": 1,
    "skin.analyze": 1
  },
  "object": "credit_balance"
}
```

**SDK Code**

```python Credits_getBalance_example
import requests

url = "https://api.morphiaone.ai/v1/credits/balance"

headers = {"X-API-Key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Credits_getBalance_example
const url = 'https://api.morphiaone.ai/v1/credits/balance';
const options = {method: 'GET', headers: {'X-API-Key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Credits_getBalance_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.morphiaone.ai/v1/credits/balance"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Credits_getBalance_example
require 'uri'
require 'net/http'

url = URI("https://api.morphiaone.ai/v1/credits/balance")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java Credits_getBalance_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.morphiaone.ai/v1/credits/balance")
  .header("X-API-Key", "<apiKey>")
  .asString();
```

```php Credits_getBalance_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.morphiaone.ai/v1/credits/balance', [
  'headers' => [
    'X-API-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Credits_getBalance_example
using RestSharp;

var client = new RestClient("https://api.morphiaone.ai/v1/credits/balance");
var request = new RestRequest(Method.GET);
request.AddHeader("X-API-Key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Credits_getBalance_example
import Foundation

let headers = ["X-API-Key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.morphiaone.ai/v1/credits/balance")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```