1. Determine data type — Equities (eq), Market (mkt), Derivatives (deriv), Finance (fins), Index (idx)
2. Check plan restrictions — Confirm whether it is available under the user's plan (refer to "Subscription Plans & API Availability" below). If the plan is unknown, present the command and clearly state the required plan
3. Check field names — Before filtering with

   -f

   , check the exact name with

   jquants schema <endpoint>

   (do not guess)
4. Choose between individual API and bulk — If it falls into any of "all tickers", "over 1 month", "large volume" → Use bulk (refer to references/commands-bulk.md). Repeated calls to individual APIs in large quantities will hit rate limits (refer to Rate Limits below). Free plan does not support CSV/bulk download (except

   mkt calendar

   )
5. Assemble the command — Place global options (

   --output

   ,

   --save

   ,

   -f

   ) before subcommands
6. Consider pipes — If there is a pipe destination, just omit

   --output

   and CSV will be streamed automatically

--fields

jquants schema <endpoint>

jquants schema                  # List of all endpoints (key, description, number of fields)
jquants schema eq.daily         # All fields of eq.daily (name, type, description)
jquants --output json schema    # Output in JSON format

category.command

eq.daily

fins.summary

mkt.short-ratio

1. Get the list of fields with

   jquants schema eq.daily

2. Copy the required field names and specify them with

   -f

3. Invalid field names will be rejected with an error (list of available fields will be displayed)

eq

eq trades

/equities/trades

• --code

  flag is not available
• Month specification in

  --date YYYY-MM

  format is supported (different from

  YYYY-MM-DD

  for individual APIs)
• Save files to current directory with

  --download

  flag

jquants eq trades --date 2025-12             # Get URL only
jquants eq trades --date 2025-12 --download  # Download file

• HTTP

  429 Too Many Requests

  is returned
• If the limit is significantly exceeded continuously, access will be completely blocked for about 5 minutes (immediate retry is counterproductive)

• Do not use individual loops for all tickers × all dates — Use

  bulk get

  to get all tickers in one request
• Do not retry immediately after receiving 429 — Wait for a while (tens of seconds to minutes) before retrying
• Filter with query parameters — Reduce unnecessary fields and date ranges, get all required data in one request

eq master

eq daily

eq earnings-calendar

fins summary

mkt calendar

eq investor-types

idx daily-topix

mkt margin-interest

mkt short-ratio

mkt short-sale-report

mkt margin-alert

idx daily

deriv options-225

eq am

fins details

fins dividend

mkt breakdown

deriv futures

deriv options

eq minute

eq trades

Plan hierarchy: Free < Light < Standard < Premium (higher plans include all APIs of lower plans)

Free plan restrictions: CSV/bulk download is not supported (except

mkt calendar

). Only API access is allowed. Data is limited to the window "12 weeks ago to 2 years and 12 weeks ago" (latest 12 weeks and historical data older than 2 years cannot be obtained).

• When asked for current day data before the update time: Inform the user that "The current day's data will be reflected around XX:XX. At present, the latest data is from the previous business day."
• Weekly data (weekend margin balance, investor sector data): Margin balance is updated around 16:30 on Tuesday, investor sector data around 18:00 on Thursday. For other days of the week, the latest data is from the previous week.
• Derivatives are updated at 27:00 (3:00 AM next day): The previous day's data will not be available until early morning of the next business day.
• When the user says "data is outdated": Check update time, weekly cycle, holidays, plan period restrictions in order.