> ## 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.

# Predict in batch

> Predict gender for up to 50 names, emails and usernames in one request.

### How batches behave

* **Mix input types freely.** Each item sets its own `type`, `country`, `forceToGenderize` and `options`.
* **Order is preserved.** `data[i]` always matches `items[i]`. Use `index`, or your own `id`, to join results back.
* **Validation is all or nothing.** One invalid item rejects the whole request with `400 invalid_input`, and nothing is charged.
* **Execution is per item.** Once the batch runs, each item succeeds or fails on its own. A `200` can contain item errors.
* **Batch items default to dataset only.** Set `options.ai_mode` to `fallback` on an item if you want AI to fill gaps, as single lookups do.
* **Credits are reserved up front.** A batch of 50 needs 50 available credits, and counts as one request toward your rate limit.

### Handling a mixed result

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

for (const item of data) {
  if (item.error) {
    // Do not resend automatically. See the Retries page.
    console.warn(`Item ${item.id ?? item.index} failed: ${item.error.code}`);
    continue;
  }
  save(item.id, item.data.result_status === "identified" ? item.data.gender : null);
}
```

<Warning>
  Never resend a whole batch because a few items failed. Successful items were already charged. Collect the failed items and decide whether to send them again in a new, smaller batch.
</Warning>

<Card title="Guide: enrich a contact list" icon="users" href="/guides/batch-gender-enrichment">
  Chunking, rate limiting and resuming a large import safely.
</Card>


## OpenAPI

````yaml POST /v1/gender/batch
openapi: 3.1.0
info:
  title: Finowl API
  version: '1.0'
  description: >
    Check emails and passwords against known data breaches, and predict gender
    from

    names, emails and usernames. Every endpoint is a JSON `POST` authenticated
    with a

    bearer API key.
servers:
  - url: https://api.finowl.co
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Breaches
    description: Check whether an email or password appears in known data breaches.
  - name: Gender
    description: >-
      Predict gender from a name, email or username, one at a time or in
      batches.
paths:
  /v1/gender/batch:
    post:
      tags:
        - Gender
      summary: Predict in batch
      description: >
        Predicts gender for 1 to 50 mixed inputs in one request. Results come
        back in the same

        order as `items`. A `200` response can contain individual item errors,
        so check each entry.


        Costs **1 credit per item**. The whole batch is rejected with
        `quota_exceeded` if you

        do not have enough credits for every item.
      operationId: predictGenderBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - items
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    $ref: '#/components/schemas/BatchItem'
            example:
              items:
                - id: lead_1
                  type: name
                  value: Alice
                - id: lead_2
                  type: email
                  value: alice.johnson@example.com
                - id: lead_3
                  type: username
                  value: prenses
                  country: TR
                  forceToGenderize: true
      responses:
        '200':
          description: The batch ran. Each entry has either `data` or `error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResult'
              example:
                data:
                  - index: 0
                    id: lead_1
                    charged_credits: 1
                    data:
                      result_status: identified
                      gender: female
                      confidence: 0.98
                  - index: 1
                    id: lead_2
                    charged_credits: 1
                    data:
                      result_status: identified
                      gender: female
                      confidence: 0.95
                  - index: 2
                    id: lead_3
                    charged_credits: 1
                    data:
                      result_status: unknown
                      gender: null
                billing_status: confirmed
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          description: >
            Every item failed. When item results are available the body has the
            same

            shape as a `200` response; otherwise it is a standard error.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/BatchResult'
                  - $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/Unavailable'
        '504':
          $ref: '#/components/responses/Unconfirmed'
components:
  schemas:
    BatchItem:
      type: object
      additionalProperties: false
      required:
        - type
        - value
      properties:
        id:
          type: string
          maxLength: 100
          description: >-
            Your own reference for the item, echoed back in the result. Must be
            unique within the batch.
        type:
          type: string
          enum:
            - name
            - email
            - username
        value:
          type: string
          minLength: 1
          maxLength: 1024
          description: The name, email or username to analyze.
        country:
          type: string
          pattern: ^[A-Za-z]{2}$
          description: Optional two-letter country hint for this item.
        forceToGenderize:
          type: boolean
          default: false
        options:
          type: object
          additionalProperties: false
          properties:
            ai_mode:
              type: string
              enum:
                - 'off'
                - fallback
                - always
              description: >-
                Batch items default to dataset only. Set `fallback` or `always`
                to use AI.
    BatchResult:
      type: object
      required:
        - data
        - billing_status
      properties:
        data:
          type: array
          description: One entry per input item, in the same order.
          items:
            type: object
            required:
              - index
            properties:
              index:
                type: integer
                description: Zero-based position of the item in your request.
              id:
                type: string
                description: The `id` you sent, if any.
              charged_credits:
                type: integer
                description: >-
                  Internal cost units for this item. This is informational; your
                  balance is charged 1 credit per item.
              data:
                $ref: '#/components/schemas/Prediction'
              error:
                type: object
                description: Present instead of `data` when this item failed.
                required:
                  - code
                  - status
                properties:
                  code:
                    type: string
                  status:
                    type: integer
                    example: 502
                  action:
                    type: string
                    description: A suggested next step, when one applies.
                    example: inspect_billing_before_retry
        billing_status:
          type: string
          description: >-
            Whether processing cost for this batch was confirmed. `unconfirmed`
            means do not assume the failed items were free.
          example: confirmed
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
          properties:
            code:
              type: string
              description: >-
                A stable, machine-readable error code. See the Errors page for
                the full list.
              example: invalid_input
    Prediction:
      type: object
      description: >
        A gender estimate. `result_status` and `gender` are always present.
        Other fields, such as

        `confidence` and `country`, are included when available, and new fields
        may be added.
      additionalProperties: true
      required:
        - result_status
        - gender
      properties:
        result_status:
          type: string
          enum:
            - identified
            - unknown
          description: >-
            `identified` when a prediction was made, `unknown` when the input
            did not carry enough signal.
        gender:
          type:
            - string
            - 'null'
          enum:
            - male
            - female
            - null
          description: The predicted gender, or `null` when `result_status` is `unknown`.
        confidence:
          type: number
          description: How confident the estimate is. Higher is more certain.
        country:
          type:
            - string
            - 'null'
          description: >-
            The country context used for the prediction. This is not the
            person's location.
  responses:
    InvalidInput:
      description: The request body is not valid. Fix the request before trying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_input
    Unauthorized:
      description: The API key is missing, malformed or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
    TooManyRequests:
      description: >
        `rate_limited` (too many requests this minute), `quota_exceeded` (not
        enough credits) or

        `provider_rate_limited` (Finowl intelligence is busy). Check the
        `Retry-After` header.
      headers:
        Retry-After:
          description: Seconds to wait before trying again.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
    Unavailable:
      description: Finowl intelligence is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_unavailable
    Unconfirmed:
      description: >-
        Finowl intelligence did not answer in time. The lookup may or may not
        have run, and the request was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_response_unconfirmed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Finowl API key, for example `finowl_3f9a...`. Create keys in the
        dashboard under **API Keys**.

````

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