Skip to main content
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

ParameterTypeApplies toDescription
fund_idintegerMost list endpointsFilter by the fund’s internal numeric ID.
fund_codestringMost list endpointsFilter by fund code (e.g. OJB). Preferred over fund_id for readability.
periodstringDocuments, line-item-values, portfolio-entriesMatch on period string prefix (e.g. 2023, 2023-Q1).
section_idintegerSections, line-item-valuesFilter by the section’s internal ID.
line_item_slugstringLine-item-valuesFilter by line item slug (e.g. net-asset-value).
qstringDocuments, sections, line-itemsFull-text search across label and text fields.
labelstringLine-item-valuesFilter values by their display label (partial match).
limitintegerAll paginated endpointsMaximum results per page.
offsetintegerAll paginated endpointsNumber 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. 
curl "https://mkk-roan.vercel.app/api/documents?fund_code=OJB"
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. 
# 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"
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.

​
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. 
# 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. 
# 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: 
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. 
# 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. 
# 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: 
{
  "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
EndpointMaximum limit
/line-items500
/stocks1000
All othersVaries; 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. 
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.