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

# BIB Search

> Search event photos by participant BIB number

## Overview

BIB Search is the API surface for **9Pic BibTrack**, our marathon BIB number recognition engine. Pass a participant's BIB number and the API returns paginated image objects for the matching photos, including large image URL, thumbnail URL, dimensions, and image ID.

<Note>
  BIB search must be enabled for the event. Check the `bib_search` flag from [Event Details](/api-reference/event-details) before calling this.
</Note>

## Endpoint

```
GET /api/v1/ext/{org_id}/event/{event_id}/bibs/{bib}
```

## Path Parameters

| Parameter  | Type   | Required | Description                                  |
| ---------- | ------ | -------- | -------------------------------------------- |
| `org_id`   | number | Yes      | Your organisation ID.                        |
| `event_id` | number | Yes      | The event to search within.                  |
| `bib`      | string | Yes      | BIB number to search for (case-insensitive). |

## Query Parameters

| Parameter   | Type   | Required | Description                                  |
| ----------- | ------ | -------- | -------------------------------------------- |
| `page`      | number | No       | Page number (default: `1`).                  |
| `page_size` | number | No       | Images per page (default: `32`, max: `100`). |

<Note>
  This endpoint returns paginated results. See the [Pagination Model](/api-reference/models/pagination).
</Note>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -i \
    -H "X-API-Key: <your_9pic_api_key>" \
    "https://api.9pic.ai/api/v1/ext/903/event/456/bibs/1234?page=1&page_size=32"
  ```

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

  response = requests.get(
      "https://api.9pic.ai/api/v1/ext/903/event/456/bibs/1234",
      headers={"X-API-Key": "<your_9pic_api_key>"},
      params={"page": 1, "page_size": 32},
  )
  print(response.status_code, response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.9pic.ai/api/v1/ext/903/event/456/bibs/1234?page=1&page_size=32",
    { headers: { "X-API-Key": "<your_9pic_api_key>" } }
  );
  console.log(await response.json());
  ```
</CodeGroup>

## Example Response

<Tabs>
  <Tab title="Images Found">
    ```json theme={null}
    {
      "responseType": "success",
      "message": "Records for bib number 1234",
      "data": {
        "images": [
          {
            "img_url": "https://photos.9pic.ai/imgs/456/large/a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244.jpg",
            "height": 4860,
            "width": 3240,
            "image_id": "a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244",
            "thumbnail_url": "https://photos.9pic.ai/imgs/456/small/a4402318-0cf4-4e1e-b8e8-ac8e8f2fc244.jpg",
            "original_url": null
          },
          {
            "img_url": "https://photos.9pic.ai/imgs/456/large/b5513429-1d05-5f2f-c9f9-bd9f9g3gd355.jpg",
            "height": 4860,
            "width": 3240,
            "image_id": "b5513429-1d05-5f2f-c9f9-bd9f9g3gd355",
            "thumbnail_url": "https://photos.9pic.ai/imgs/456/small/b5513429-1d05-5f2f-c9f9-bd9f9g3gd355.jpg",
            "original_url": null
          }
        ],
        "pagination": {
          "total": 8,
          "currentPage": 1,
          "totalPages": 1,
          "hasNextPage": false,
          "hasPreviousPage": false,
          "page_size": 32
        }
      }
    }
    ```
  </Tab>

  <Tab title="No Matches">
    ```json theme={null}
    {
      "responseType": "success",
      "message": "No images found",
      "data": {
        "images": [],
        "pagination": {
          "total": 0,
          "currentPage": 0,
          "totalPages": 0,
          "hasNextPage": false,
          "hasPreviousPage": false,
          "page_size": 32
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Response Models

| Model                                                                                    | Description                                            |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| <a href="/api-reference/models/search-responses#bibsearchresponse">BibSearchResponse</a> | Top-level BIB search response envelope.                |
| <a href="/api-reference/models/image">ImageItem</a>                                      | Image object returned inside `data.images[]`.          |
| <a href="/api-reference/models/pagination">PaginationInfo</a>                            | Pagination metadata returned inside `data.pagination`. |

<Tip>
  `original_url` is `null` in the standard BIB search response. Use [Download Original Photos](/api-reference/download-original-photos) when you need access to original files.
</Tip>

## Error Responses

| Status | Meaning                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------- |
| `401`  | API key is missing.                                                                                     |
| `403`  | API key is invalid, inactive, token/event ownership mismatch, or BIB search is disabled for this event. |
| `404`  | Event configuration not found.                                                                          |
| `429`  | Rate limit exceeded. Back off and retry.                                                                |
| `500`  | Internal failure.                                                                                       |

See [Errors](/api-reference/errors) for canonical descriptions and retry guidance.