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

# Filter and Search Results in the MKK API

> Use fund, period, section, and text-search filters across every endpoint, and paginate large result sets with limit and offset parameters.

Most list endpoints in the MKK API accept a common set of query parameters that let you narrow results by fund, time period, section, or free-text search. Understanding how these parameters compose — and how pagination works — will help you write precise queries rather than fetching and filtering data client-side.

## Common filter parameters

| Parameter        | Type    | Applies to                                     | Description                                                                 |
| ---------------- | ------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
| `fund_id`        | integer | Most list endpoints                            | Filter by the fund's internal numeric ID.                                   |
| `fund_code`      | string  | Most list endpoints                            | Filter by fund code (e.g. `OJB`). Preferred over `fund_id` for readability. |
| `period`         | string  | Documents, line-item-values, portfolio-entries | Match on period string prefix (e.g. `2023`, `2023-Q1`).                     |
| `section_id`     | integer | Sections, line-item-values                     | Filter by the section's internal ID.                                        |
| `line_item_slug` | string  | Line-item-values                               | Filter by line item slug (e.g. `net-asset-value`).                          |
| `q`              | string  | Documents, sections, line-items                | Full-text search across label and text fields.                              |
| `label`          | string  | Line-item-values                               | Filter values by their display label (partial match).                       |
| `limit`          | integer | All paginated endpoints                        | Maximum results per page.                                                   |
| `offset`         | integer | All paginated endpoints                        | Number of results to skip.                                                  |

## Using fund\_code vs fund\_id

Both `fund_code` and `fund_id` identify the same fund, but `fund_code` is a human-readable string (e.g. `OJB`) while `fund_id` is an opaque integer. Use `fund_code` when you are working interactively or constructing URLs by hand — it is stable across environments and easier to read in logs.

<CodeGroup>
  ```bash fund_code (recommended) theme={null}
  curl "https://mkk-roan.vercel.app/api/documents?fund_code=OJB"
  ```

  ```bash fund_id theme={null}
  curl "https://mkk-roan.vercel.app/api/documents?fund_id=1"
  ```
</CodeGroup>

When both parameters are present, `fund_code` takes precedence.

## Filtering by period

The `period` parameter performs a prefix match on the period string stored for each document or value. This means you can filter at any level of granularity — year, quarter, or full period string.

```bash theme={null}
# All documents for 2023 (any quarter or month)
curl "https://mkk-roan.vercel.app/api/documents?fund_code=OJB&period=2023"

# Only Q1 documents
curl "https://mkk-roan.vercel.app/api/documents?fund_code=OJB&period=2023-Q1"

# Exact period match
curl "https://mkk-roan.vercel.app/api/line-item-values?fund_code=OJB&period=2023-Q4"
```

<Note>
  Period strings are stored as-is from the MKK disclosure data. Common formats include `YYYY`, `YYYY-QN`, and `YYYY-MM`. Pass the prefix that matches the granularity you need.
</Note>

## Text search with the q parameter

Use the `q` parameter on the `/documents`, `/sections`, and `/line-items` endpoints to search by label or text content. The search is case-insensitive and matches partial strings.

```bash theme={null}
# Search documents by keyword
curl "https://mkk-roan.vercel.app/api/documents?q=yatirim"

# Search sections by name
curl "https://mkk-roan.vercel.app/api/sections?fund_code=OJB&q=portfolio"

# Search line items by label
curl "https://mkk-roan.vercel.app/api/line-items?q=net+asset"
```

## Filtering line item values by section and slug

On `/line-item-values` (and its alias `/key-values`), use `section_id` to restrict results to a specific section of a document, and `line_item_slug` to retrieve values for a specific line item across all documents or periods.

```bash theme={null}
# All net-asset-value entries for OJB in 2023
curl "https://mkk-roan.vercel.app/api/line-item-values?fund_code=OJB&period=2023&line_item_slug=net-asset-value"

# All values in a specific section
curl "https://mkk-roan.vercel.app/api/line-item-values?section_id=7&fund_code=OJB"
```

You can also combine `label` with other filters to match values by their display label:

```bash theme={null}
curl "https://mkk-roan.vercel.app/api/line-item-values?fund_code=OJB&label=Net+Varlık"
```

## Filtering portfolio entries

Use `/portfolio-entries` with `fund_code`, `period`, and `section` to find holdings for a given fund and period.

```bash theme={null}
# All portfolio entries for OJB in Q4 2023
curl "https://mkk-roan.vercel.app/api/portfolio-entries?fund_code=OJB&period=2023-Q4"

# Narrow by section name
curl "https://mkk-roan.vercel.app/api/portfolio-entries?fund_code=OJB&period=2023-Q4&section=hisse"
```

## Pagination

All list endpoints return a `total` field alongside the `data` array. Use `limit` and `offset` together to page through results.

```bash theme={null}
# First page of 50
curl "https://mkk-roan.vercel.app/api/portfolio-entries?fund_code=OJB&limit=50&offset=0"

# Second page
curl "https://mkk-roan.vercel.app/api/portfolio-entries?fund_code=OJB&limit=50&offset=50"
```

A typical paginated response looks like this:

```json theme={null}
{
  "total": 348,
  "limit": 50,
  "offset": 50,
  "portfolio_entries": [ ... ]
}
```

The outer array field name matches the resource (`funds`, `documents`, `line_items`, `portfolio_entries`, etc.).

Use `total` to determine how many pages exist: `ceil(total / limit)`. Keep incrementing `offset` by `limit` until `offset >= total`.

**Per-endpoint limits**

| Endpoint      | Maximum `limit`                   |
| ------------- | --------------------------------- |
| `/line-items` | 500                               |
| `/stocks`     | 1000                              |
| All others    | Varies; check `total` in response |

## Paginating embedded portfolio in fund detail

When using `include_portfolio=true` on `GET /funds/{fundId}`, the embedded portfolio list is paginated with its own `portfolio_limit` and `portfolio_offset` parameters — separate from the top-level `limit` and `offset`.

```bash theme={null}
curl "https://mkk-roan.vercel.app/api/funds/OJB?include_portfolio=true&portfolio_limit=50&portfolio_offset=100"
```

The response includes a `portfolio_entry_count` field at the fund level indicating the full count of portfolio entries for that fund, and `portfolio_limit`/`portfolio_offset` reflecting the pagination applied to the embedded array.