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

# Pending scores

> Why a field can come back without a score, and how to ask again.

We don't score every field in England in advance. When you ask about a field we haven't scored yet, we queue it for scoring and answer straight away with what we have.

## The three statuses

Each field in an answer has a `status`:

| Status | Meaning | `score`, `band`, `horizons` | `reasons` |
| - | - | - | - |
| `scored` | Scored under the current model. | Filled in | Up to 3 |
| `pending` | Not scored yet. It has been queued. | `null` | Empty |
| `not_open_land` | Built on, or too small to be a field. We don't score it. | See below | See below |

`/v1/scores` only returns open fields, so its fields are always `scored` or `pending`. You'll see `not_open_land` only from `/v1/fields/{field_id}`, when you ask about a piece of land that isn't an open field, such as a garden. Treat it as having no score.

## What happens when you ask

**1. You ask**

You call `/v1/scores` or `/v1/fields/{field_id}`, and an open field in the answer has no score.

**2. We queue it, once**

We queue the field for scoring. Asking again, by you or anyone else, doesn't queue it a second time while it waits.

**3. It is scored**

Scoring usually takes a few minutes. API requests wait behind people using our site, so it can take longer when we're busy.

**4. You ask again**

The field comes back `scored`, with its score, band, horizons and reasons.

> [!NOTE]
>
> A call with pending fields is still an answer, so it counts against your quota. Each time you ask again counts too. Poll sparingly.

Scores belong to a scoring model, named in `model_version`. When we bring in a new model, fields not yet scored under it come back `pending` again until they are.

## Asking again

Wait a minute or two, then back off. Ask only about the fields still pending, with `/v1/fields/{field_id}`, rather than repeating the whole search.

```python Python theme={null}
import os
import time
import requests

API = "https://api.checkthatfield.com/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['CTF_KEY']}"


def wait_for_score(field_id, tries=6):
    delay = 60
    for _ in range(tries):
        r = session.get(f"{API}/fields/{field_id}", timeout=30)
        r.raise_for_status()
        field = r.json()
        if field["status"] != "pending":
            return field
        time.sleep(delay)
        delay = min(delay * 2, 15 * 60)  # 1, 2, 4, 8, 15, 15 minutes
    return None  # still pending: try again later
```

```javascript JavaScript theme={null}
// Server-side only.
const API = "https://api.checkthatfield.com/v1";
const headers = { Authorization: `Bearer ${process.env.CTF_KEY}` };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function waitForScore(fieldId, tries = 6) {
  let delay = 60_000;
  for (let i = 0; i < tries; i++) {
    const res = await fetch(`${API}/fields/${fieldId}`, { headers });
    if (!res.ok) throw new Error((await res.json()).error.message);
    const field = await res.json();
    if (field.status !== "pending") return field;
    await sleep(delay);
    delay = Math.min(delay * 2, 15 * 60_000);
  }
  return null; // still pending: try again later
}
```

> [!TIP]
>
> In your own product, show a pending field as "being checked" and let the reader come back, rather than holding a page open while you poll.

## If a field stays pending

Now and then scoring fails. A field whose scoring failed in the last day isn't queued again on every request, so it stays `pending` for a while. After a day, asking about it queues it again. If a field stays pending for longer than that, email [hello@checkthatfield.com](mailto:hello@checkthatfield.com) with its `field_id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.