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

# Reading predictions

> How to interpret gender predictions, use confidence and AI modes, and handle unknown results responsibly.

Every gender endpoint returns a prediction object:

```json theme={null}
{
  "data": {
    "result_status": "identified",
    "gender": "female",
    "confidence": 0.97,
    "country": "US"
  }
}
```

## Fields

<ResponseField name="result_status" type="string" required>
  `identified` when Finowl intelligence made a prediction, `unknown` when the input did not carry enough signal. Both are successful responses.
</ResponseField>

<ResponseField name="gender" type="string | null" required>
  `male` or `female` when identified, `null` when unknown.
</ResponseField>

<ResponseField name="confidence" type="number">
  How confident the estimate is. Higher means more certain. Use it to decide when a prediction is strong enough for your use case.
</ResponseField>

<ResponseField name="country" type="string | null">
  The country context used for the prediction. This is never proof of where a person lives.
</ResponseField>

<Note>
  The prediction object can include additional fields, and new ones may be added over time. Read the fields you need and ignore the rest.
</Note>

## Handle unknown results

`unknown` is a real answer, not an error. You are charged for it, and you should store it so you do not ask again.

```javascript theme={null}
const { data } = await response.json();

const gender = data.result_status === "identified" ? data.gender : null;
```

Never replace `unknown` with a default value. A contact with no prediction is better than a contact with a wrong one.

## Use a confidence threshold

Pick a threshold that matches the cost of being wrong:

| Use case | Suggested approach |
| - | - |
| Aggregate analytics, such as audience mix | Use all identified predictions |
| Light personalization, such as a greeting | Use only high confidence predictions |
| Anything with real consequences for a person | Do not use predictions. Ask the person. |

## AI modes

Finowl intelligence first looks the input up in a large name dataset. The `options.ai_mode` field controls whether AI is used when the dataset has no answer.

| Mode | Behavior | Default for |
| - | - | - |
| `fallback` | Dataset first, AI only when the dataset has no answer | Single lookups |
| `off` | Dataset only. More `unknown` results, most predictable | Batch items |
| `always` | Always use AI | Neither |

```json theme={null}
{ "name": "Kiri", "options": { "ai_mode": "always" } }
```

The mode does not change what you pay. Every lookup costs 1 credit.

## Using predictions responsibly

A gender prediction is a statistical guess based on how a name is typically used. It does not tell you how a person identifies, and it is wrong for some people every time.

* Use predictions for aggregate insight and low-stakes personalization only.
* Never use them to decide eligibility, pricing, access or anything else that significantly affects someone.
* Give people a way to state or correct their own gender, and always prefer what they tell you.
* Mention the lookup in your privacy notice, because it processes personal data.


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