{
 "openapi": "3.1.0",
 "info": {
  "title": "Fundai Data API",
  "version": "1",
  "description": "Iran's stock market data: companies, daily trading, Codal statements, ratios, monthly sales, IME trades, dividends, portfolios and the multi-step screener. Every successful request that returns rows costs `x-cost` credits for each started block of `x-cost-per-rows` rows (daily trading 30, everything else 20): a page of 21 to 40 screener rows costs twice the price, so a large page is never cheaper than small ones. Failures and empty answers are free. A first key on an account with a verified phone comes with 100 free trial credits. Once an account has bought credit, a sandbox key (`fai-test_`) gets every endpoint's sample data free, in the real shape, for building and testing. Every answer says in `meta.updated_at` when its data last changed. For personal, non-commercial use only; commercial use needs a formal request at https://fundai.ir/enterprise and Fundai's written approval.",
  "x-fa": "داده‌ی بازار سرمایه‌ی ایران: شرکت‌ها، معاملات روزانه، صورت‌های مالی کدال، نسبت‌ها، فروش ماهانه، معاملات بورس کالا، سود نقدی، پرتفوی‌ها و فیلتر چندمرحله‌ای. هر درخواست موفقی که داده برگرداند، برای هر `x-cost-per-rows` ردیف (معاملات روزانه ۳۰ ردیف و بقیه‌ی داده‌ها ۲۰ ردیف) به اندازه‌ی `x-cost` اعتبار کم می‌کند: صفحه‌ای با ۲۱ تا ۴۰ ردیف از فیلتر دو برابر قیمت دارد، پس صفحه‌ی بزرگ هیچ‌وقت ارزان‌تر از چند صفحه‌ی کوچک نیست. درخواست ناموفق و پاسخ خالی رایگان است. اولین کلید حسابی که شماره‌ی موبایلش تأیید شده ۱۰۰ اعتبار آزمایشی هدیه دارد. بعد از اولین خرید اعتبار، کلید آزمایشی (`fai-test_`) از هر مسیر داده‌ی نمونه را با همان شکل واقعی و رایگان می‌گیرد تا برنامه‌تان را بسازید و تست کنید. هر پاسخ در `meta.updated_at` می‌گوید داده‌اش آخرین بار کی به‌روز شده است. فقط برای استفاده‌ی شخصی و غیرتجاری؛ استفاده‌ی تجاری با درخواست رسمی از https://fundai.ir/enterprise و تأیید کتبی فاندای ممکن است.",
  "contact": {
   "email": "cooperation@fundai.ir"
  }
 },
 "servers": [
  {
   "url": "https://fundai.ir/api/data/v1"
  }
 ],
 "security": [
  {
   "bearer": []
  }
 ],
 "paths": {
  "/me/": {
   "get": {
    "operationId": "me",
    "tags": [
     "account"
    ],
    "summary": "Your account",
    "description": "Your balance, today's requests and your limits. Free, and a good first call to check a key.",
    "x-fa": {
     "summary": "حساب شما",
     "description": "اعتبار باقی‌مانده، درخواست‌های امروز و سقف‌هایتان. رایگان است و برای امتحان کلید اولین درخواست خوبی است."
    },
    "x-cost": 0,
    "x-cost-per-rows": 0,
    "x-kind": "free",
    "x-page-cap": 0,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "object",
           "properties": {
            "client": {
             "type": "string",
             "description": "Your account name.",
             "x-fa": "نام حساب شما."
            },
            "key": {
             "type": "object",
             "description": "`{label, masked, sandbox}` of the key you called with; `sandbox` is true for a test key, whose limits below are the sandbox's.",
             "x-fa": "نام، شکل پوشیده و نوع کلیدی که با آن درخواست دادید؛ برای کلید آزمایشی `sandbox` برابر true است و سقف‌های زیر مال محیط آزمایشی است."
            },
            "credits": {
             "type": "integer",
             "description": "Credits left.",
             "x-fa": "اعتبار باقی‌مانده.",
             "x-unit": "credit"
            },
            "used_today": {
             "type": "integer",
             "description": "Requests counted today against the daily limit.",
             "x-fa": "درخواست‌هایی که امروز از سقف روزانه کم شده است."
            },
            "limits": {
             "type": "object",
             "description": "`tier` (your usage tier), `per_minute`, `per_day`, `concurrency`, `repeat_grace_seconds`, `idempotency_hours`, and `next_tier`: `{level, credits}`, the credits still to spend to reach the next tier, or null at the top. Your tier rises on its own as your calls spend credits. `night`: `{from, to, factor, active}`, the quiet hours (Tehran) when `per_minute` and `concurrency` double, and whether it is now; the figures above already include it.",
             "x-fa": "سطح استفاده‌ی شما، سقف دقیقه، سقف روز، تعداد درخواست هم‌زمان، مدت تکرار رایگان، چند ساعتی که Idempotency-Key معتبر است و next_tier: اعتباری که تا سطح بعد باید مصرف شود، یا null در بالاترین سطح. سطح با مصرف اعتبار خودکار بالا می‌رود. night: ساعت‌های خلوت (به وقت تهران) که سقف دقیقه و درخواست هم‌زمان دو برابر می‌شود و اینکه الان در آن هستیم یا نه؛ عددهای بالا همین را حساب کرده‌اند."
            }
           }
          }
         }
        },
        "example": {
         "data": {
          "client": "user-0193…",
          "key": {
           "label": "server",
           "masked": "fai-api_••••••••Xk2Q",
           "sandbox": false
          },
          "credits": 4812,
          "used_today": 188,
          "limits": {
           "tier": 2,
           "per_minute": 60,
           "per_day": 5000,
           "concurrency": 4,
           "repeat_grace_seconds": 60,
           "idempotency_hours": 24,
           "next_tier": {
            "level": 3,
            "credits": 6400
           },
           "night": {
            "from": "00:00",
            "to": "07:00",
            "factor": 2,
            "active": false
           }
          }
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/datasets/": {
   "get": {
    "operationId": "datasets",
    "tags": [
     "account"
    ],
    "summary": "Price list",
    "description": "Every dataset with its live price, page cap and whether your account can read it. Free.",
    "x-fa": {
     "summary": "فهرست قیمت",
     "description": "همه‌ی داده‌ها با قیمت فعلی، سقف صفحه و اینکه حساب شما به آن دسترسی دارد یا نه. رایگان است."
    },
    "x-cost": 0,
    "x-cost-per-rows": 0,
    "x-kind": "free",
    "x-page-cap": 0,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "key": {
              "type": "string",
              "description": "Dataset id.",
              "x-fa": "شناسه‌ی داده."
             },
             "group": {
              "type": "string",
              "description": "reference, market, statements, activity, corporate or screener.",
              "x-fa": "گروه داده."
             },
             "kind": {
              "type": "string",
              "description": "`reference`, `raw` (as the source published it) or `processed` (built by us).",
              "x-fa": "`reference` فهرست پایه، `raw` همان‌طور که منبع منتشر کرده، `processed` ساخته‌ی ما."
             },
             "method": {
              "type": "string",
              "description": "HTTP method.",
              "x-fa": "متد HTTP."
             },
             "path": {
              "type": "string",
              "description": "Path under /api/data/v1.",
              "x-fa": "مسیر زیر /api/data/v1."
             },
             "cost": {
              "type": "integer",
              "description": "Credits for each block of `per_rows` rows a successful request returns.",
              "x-fa": "اعتباری که درخواست موفق برای هر `per_rows` ردیف کم می‌کند.",
              "x-unit": "credit"
             },
             "per_rows": {
              "type": "integer",
              "description": "Rows one `cost` buys; a request pays once per started block, so 21 screener rows cost twice.",
              "x-fa": "تعداد ردیفی که یک بار `cost` می‌خرد؛ هر بلوکِ شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف از فیلتر دو برابر قیمت دارد."
             },
             "max_limit": {
              "type": "integer",
              "description": "Largest `limit` this dataset accepts.",
              "x-fa": "بیشترین `limit` که این داده می‌پذیرد."
             },
             "available": {
              "type": "boolean",
              "description": "Whether your account can read it.",
              "x-fa": "اینکه حساب شما به آن دسترسی دارد."
             }
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "key": "prices",
           "group": "market",
           "kind": "raw",
           "method": "GET",
           "path": "/companies/{company}/prices/",
           "cost": 3,
           "per_rows": 30,
           "max_limit": 1000,
           "available": true
          }
         ]
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/usage/": {
   "get": {
    "operationId": "usage",
    "tags": [
     "account"
    ],
    "summary": "Your usage",
    "description": "Calls and credits per day and dataset, newest first. Free.",
    "x-fa": {
     "summary": "مصرف شما",
     "description": "درخواست‌ها و اعتبار مصرف‌شده به تفکیک روز و داده، از تازه به قدیم. رایگان است."
    },
    "x-cost": 0,
    "x-cost-per-rows": 0,
    "x-kind": "free",
    "x-page-cap": 0,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "date": {
              "type": "string",
              "format": "date",
              "description": "Day, Tehran time.",
              "x-fa": "روز، به وقت تهران."
             },
             "date_jalali": {
              "type": "string",
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "dataset": {
              "type": [
               "string",
               "null"
              ],
              "description": "Dataset id, null for a free endpoint.",
              "x-fa": "شناسه‌ی داده، برای درخواست رایگان null."
             },
             "calls": {
              "type": "integer",
              "description": "Requests that day.",
              "x-fa": "تعداد درخواست."
             },
             "charged_calls": {
              "type": "integer",
              "description": "Requests that cost credit.",
              "x-fa": "درخواست‌هایی که اعتبار کم کرد."
             },
             "credits": {
              "type": "integer",
              "description": "Credits spent.",
              "x-fa": "اعتبار مصرف‌شده.",
              "x-unit": "credit"
             },
             "errors": {
              "type": "integer",
              "description": "Requests that failed (never charged).",
              "x-fa": "درخواست‌های ناموفق که هزینه‌ای نداشتند."
             }
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "date": "2026-11-07",
           "dataset": "prices",
           "calls": 412,
           "charged_calls": 398,
           "credits": 398,
           "errors": 3
          }
         ]
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "name": "days",
      "in": "query",
      "required": false,
      "description": "How many days back, 1 to 90.",
      "x-fa": "چند روز گذشته، از ۱ تا ۹۰.",
      "schema": {
       "type": "integer",
       "default": 30
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/": {
   "get": {
    "operationId": "companies",
    "tags": [
     "reference"
    ],
    "summary": "Companies",
    "description": "Every listed company we cover, with the `slug` every other path takes.",
    "x-fa": {
     "summary": "فهرست شرکت‌ها",
     "description": "همه‌ی شرکت‌های بورسی که پوشش می‌دهیم، با `slug` که بقیه‌ی مسیرها با آن کار می‌کنند."
    },
    "x-cost": 1,
    "x-cost-per-rows": 1000,
    "x-kind": "reference",
    "x-page-cap": 1000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "slug": {
              "type": "string",
              "description": "Stable id used in every other path.",
              "x-fa": "شناسه‌ی ثابت که در بقیه‌ی مسیرها به کار می‌رود."
             },
             "symbol": {
              "type": "string",
              "description": "Trading symbol as TSETMC writes it.",
              "x-fa": "نماد معاملاتی به همان شکلی که سایت بورس می‌نویسد."
             },
             "name": {
              "type": "string",
              "description": "Company name in Persian.",
              "x-fa": "نام شرکت."
             },
             "name_en": {
              "type": [
               "string",
               "null"
              ],
              "description": "English name, when we have one.",
              "x-fa": "نام انگلیسی، اگر داشته باشیم."
             },
             "ticker_en": {
              "type": [
               "string",
               "null"
              ],
              "description": "Latin ticker, when we have one.",
              "x-fa": "نماد لاتین، اگر داشته باشیم."
             },
             "industry": {
              "type": [
               "object",
               "null"
              ],
              "description": "`{slug, name}` of its industry.",
              "x-fa": "صنعت شرکت به شکل `{slug, name}`."
             },
             "tsetmc_id": {
              "type": [
               "string",
               "null"
              ],
              "description": "The instrument id on tsetmc.com.",
              "x-fa": "شناسه‌ی نماد در سایت tsetmc.com."
             },
             "board": {
              "type": [
               "string",
               "null"
              ],
              "description": "Market and board as TSETMC words it.",
              "x-fa": "بازار و تابلوی معاملاتی به عبارت سایت بورس."
             },
             "trading_state": {
              "type": [
               "string",
               "null"
              ],
              "description": "`trading` or `halted`.",
              "x-fa": "`trading` یعنی باز و `halted` یعنی متوقف."
             },
             "fiscal_year_end": {
              "type": [
               "string",
               "null"
              ],
              "description": "Month and day the fiscal year ends, Jalali `MM-DD`.",
              "x-fa": "ماه و روز پایان سال مالی به شمسی، به شکل `MM-DD`."
             },
             "national_id": {
              "type": [
               "string",
               "null"
              ],
              "description": "National id of the company.",
              "x-fa": "شناسه‌ی ملی شرکت."
             },
             "is_primary_listing": {
              "type": "boolean",
              "description": "False for a second listing of the same company (rights, another board).",
              "x-fa": "برای نماد دوم همان شرکت (حق تقدم یا تابلوی دیگر) false است."
             },
             "updated_at": {
              "type": [
               "string",
               "null"
              ],
              "format": "date-time",
              "description": "Last change to this row, ISO 8601.",
              "x-fa": "آخرین تغییر این ردیف به قالب ISO 8601."
             },
             "updated_at_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "slug": "foulad",
           "symbol": "فولاد",
           "name": "فولاد مبارکه اصفهان",
           "name_en": "Mobarakeh Steel",
           "ticker_en": "FOLD",
           "industry": {
            "slug": "basic-metals",
            "name": "فلزات اساسی"
           },
           "tsetmc_id": "46348559193224090",
           "board": "بازار اول (تابلوی اصلی) بورس",
           "trading_state": "trading",
           "fiscal_year_end": "12-29",
           "national_id": "10260145720",
           "is_primary_listing": true,
           "updated_at": "2026-11-06T21:14:03+03:30"
          }
         ],
         "next_cursor": "WzEyXQ",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "name": "industry",
      "in": "query",
      "required": false,
      "description": "Only this industry's `slug`.",
      "x-fa": "فقط شرکت‌های این صنعت (`slug` صنعت).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "symbol",
      "in": "query",
      "required": false,
      "description": "Find one symbol.",
      "x-fa": "پیدا کردن یک نماد.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "primary",
      "in": "query",
      "required": false,
      "description": "Leave out second listings (rights, other boards).",
      "x-fa": "نمادهای دوم همان شرکت (حق تقدم و تابلوی دیگر) را کنار می‌گذارد.",
      "schema": {
       "type": "boolean",
       "default": true
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/": {
   "get": {
    "operationId": "company",
    "tags": [
     "reference"
    ],
    "summary": "One company",
    "description": "One company's directory row, plus its activity, CEO, auditor and website.",
    "x-fa": {
     "summary": "یک شرکت",
     "description": "اطلاعات یک شرکت، به‌علاوه‌ی موضوع فعالیت، مدیرعامل، حسابرس و وب‌سایت."
    },
    "x-cost": 1,
    "x-cost-per-rows": 1,
    "x-kind": "reference",
    "x-page-cap": 1,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "object",
           "properties": {
            "slug": {
             "type": "string",
             "description": "Stable id used in every other path.",
             "x-fa": "شناسه‌ی ثابت که در بقیه‌ی مسیرها به کار می‌رود."
            },
            "symbol": {
             "type": "string",
             "description": "Trading symbol as TSETMC writes it.",
             "x-fa": "نماد معاملاتی به همان شکلی که سایت بورس می‌نویسد."
            },
            "name": {
             "type": "string",
             "description": "Company name in Persian.",
             "x-fa": "نام شرکت."
            },
            "name_en": {
             "type": [
              "string",
              "null"
             ],
             "description": "English name, when we have one.",
             "x-fa": "نام انگلیسی، اگر داشته باشیم."
            },
            "ticker_en": {
             "type": [
              "string",
              "null"
             ],
             "description": "Latin ticker, when we have one.",
             "x-fa": "نماد لاتین، اگر داشته باشیم."
            },
            "industry": {
             "type": [
              "object",
              "null"
             ],
             "description": "`{slug, name}` of its industry.",
             "x-fa": "صنعت شرکت به شکل `{slug, name}`."
            },
            "tsetmc_id": {
             "type": [
              "string",
              "null"
             ],
             "description": "The instrument id on tsetmc.com.",
             "x-fa": "شناسه‌ی نماد در سایت tsetmc.com."
            },
            "board": {
             "type": [
              "string",
              "null"
             ],
             "description": "Market and board as TSETMC words it.",
             "x-fa": "بازار و تابلوی معاملاتی به عبارت سایت بورس."
            },
            "trading_state": {
             "type": [
              "string",
              "null"
             ],
             "description": "`trading` or `halted`.",
             "x-fa": "`trading` یعنی باز و `halted` یعنی متوقف."
            },
            "fiscal_year_end": {
             "type": [
              "string",
              "null"
             ],
             "description": "Month and day the fiscal year ends, Jalali `MM-DD`.",
             "x-fa": "ماه و روز پایان سال مالی به شمسی، به شکل `MM-DD`."
            },
            "national_id": {
             "type": [
              "string",
              "null"
             ],
             "description": "National id of the company.",
             "x-fa": "شناسه‌ی ملی شرکت."
            },
            "is_primary_listing": {
             "type": "boolean",
             "description": "False for a second listing of the same company (rights, another board).",
             "x-fa": "برای نماد دوم همان شرکت (حق تقدم یا تابلوی دیگر) false است."
            },
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time",
             "description": "Last change to this row, ISO 8601.",
             "x-fa": "آخرین تغییر این ردیف به قالب ISO 8601."
            },
            "updated_at_jalali": {
             "type": [
              "string",
              "null"
             ],
             "description": "The same date in the Jalali calendar.",
             "x-fa": "همان تاریخ به شمسی."
            },
            "activity": {
             "type": [
              "string",
              "null"
             ],
             "description": "Line of business as filed.",
             "x-fa": "موضوع فعالیت به همان شکل که ثبت شده."
            },
            "ceo": {
             "type": [
              "string",
              "null"
             ],
             "description": "Chief executive.",
             "x-fa": "مدیرعامل."
            },
            "auditor": {
             "type": [
              "string",
              "null"
             ],
             "description": "Auditor.",
             "x-fa": "حسابرس."
            },
            "website": {
             "type": [
              "string",
              "null"
             ],
             "description": "Website.",
             "x-fa": "وب‌سایت."
            }
           }
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": {
          "slug": "foulad",
          "symbol": "فولاد",
          "name": "فولاد مبارکه اصفهان",
          "activity": "تولید و فروش انواع محصولات فولادی",
          "ceo": "…",
          "auditor": "…",
          "website": "msc.ir"
         },
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/industries/": {
   "get": {
    "operationId": "industries",
    "tags": [
     "reference"
    ],
    "summary": "Industries",
    "description": "The industry tree, two levels deep.",
    "x-fa": {
     "summary": "فهرست صنعت‌ها",
     "description": "درخت صنعت‌ها در دو سطح."
    },
    "x-cost": 1,
    "x-cost-per-rows": 500,
    "x-kind": "reference",
    "x-page-cap": 500,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "slug": {
              "type": "string",
              "description": "Industry id.",
              "x-fa": "شناسه‌ی صنعت."
             },
             "name": {
              "type": "string",
              "description": "Name in Persian.",
              "x-fa": "نام صنعت."
             },
             "name_en": {
              "type": [
               "string",
               "null"
              ],
              "description": "English name.",
              "x-fa": "نام انگلیسی."
             },
             "parent": {
              "type": [
               "string",
               "null"
              ],
              "description": "Parent industry's slug, null at the top.",
              "x-fa": "شناسه‌ی صنعت بالاتر، در سطح اول null."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "slug": "basic-metals",
           "name": "فلزات اساسی",
           "name_en": "Basic Metals",
           "parent": null
          }
         ],
         "next_cursor": null,
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/prices/": {
   "get": {
    "operationId": "prices",
    "tags": [
     "market"
    ],
    "summary": "Daily trading",
    "description": "One row per trading session, newest first, as TSETMC published it: prices, volume, value, market cap and the individual/institutional split. Not adjusted for capital raises or dividends.",
    "x-fa": {
     "summary": "معاملات روزانه",
     "description": "برای هر روز معاملاتی یک ردیف، از تازه به قدیم، همان‌طور که سایت بورس منتشر کرده: قیمت، حجم، ارزش، ارزش بازار و تفکیک حقیقی و حقوقی. قیمت‌ها برای افزایش سرمایه و سود نقدی تعدیل نشده‌اند."
    },
    "x-cost": 3,
    "x-cost-per-rows": 30,
    "x-kind": "raw",
    "x-page-cap": 1000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "date": {
              "type": "string",
              "format": "date",
              "description": "Session day, Tehran time.",
              "x-fa": "روز معاملاتی به وقت تهران."
             },
             "date_jalali": {
              "type": "string",
              "description": "The same day in Jalali.",
              "x-fa": "همان روز به شمسی."
             },
             "trading_state": {
              "type": [
               "string",
               "null"
              ],
              "description": "`trading` or `halted`.",
              "x-fa": "`trading` باز، `halted` متوقف."
             },
             "close_rial": {
              "type": "number",
              "description": "Closing price.",
              "x-fa": "قیمت پایانی.",
              "x-unit": "rial"
             },
             "last_rial": {
              "type": "number",
              "description": "Last trade price.",
              "x-fa": "قیمت آخرین معامله.",
              "x-unit": "rial"
             },
             "previous_close_rial": {
              "type": "number",
              "description": "Previous session's close.",
              "x-fa": "قیمت پایانی روز قبل.",
              "x-unit": "rial"
             },
             "volume": {
              "type": "number",
              "description": "Shares traded.",
              "x-fa": "حجم معاملات.",
              "x-unit": "share"
             },
             "value_rial": {
              "type": "number",
              "description": "Value traded.",
              "x-fa": "ارزش معاملات.",
              "x-unit": "rial"
             },
             "trades": {
              "type": "number",
              "description": "Number of trades.",
              "x-fa": "تعداد معاملات."
             },
             "market_cap_rial": {
              "type": "number",
              "description": "Shares outstanding times close.",
              "x-fa": "ارزش بازار: تعداد سهام ضرب در قیمت پایانی.",
              "x-unit": "rial"
             },
             "shares_outstanding": {
              "type": "number",
              "description": "Shares outstanding.",
              "x-fa": "تعداد سهام.",
              "x-unit": "share"
             },
             "average_volume_30d": {
              "type": [
               "number",
               "null"
              ],
              "description": "Mean volume over the last 30 sessions, this one included.",
              "x-fa": "میانگین حجم ۳۰ روز معاملاتی اخیر، با همین روز.",
              "x-unit": "share"
             },
             "individual_buy_volume": {
              "type": "number",
              "description": "Shares bought by individuals (حقیقی).",
              "x-fa": "حجم خرید حقیقی.",
              "x-unit": "share"
             },
             "individual_sell_volume": {
              "type": "number",
              "description": "Shares sold by individuals.",
              "x-fa": "حجم فروش حقیقی.",
              "x-unit": "share"
             },
             "institutional_buy_volume": {
              "type": "number",
              "description": "Shares bought by institutions (حقوقی).",
              "x-fa": "حجم خرید حقوقی.",
              "x-unit": "share"
             },
             "institutional_sell_volume": {
              "type": "number",
              "description": "Shares sold by institutions.",
              "x-fa": "حجم فروش حقوقی.",
              "x-unit": "share"
             },
             "individual_buyers": {
              "type": "number",
              "description": "Individual buyers.",
              "x-fa": "تعداد خریداران حقیقی."
             },
             "individual_sellers": {
              "type": "number",
              "description": "Individual sellers.",
              "x-fa": "تعداد فروشندگان حقیقی."
             },
             "institutional_buyers": {
              "type": "number",
              "description": "Institutional buyers.",
              "x-fa": "تعداد خریداران حقوقی."
             },
             "institutional_sellers": {
              "type": "number",
              "description": "Institutional sellers.",
              "x-fa": "تعداد فروشندگان حقوقی."
             },
             "individual_buy_per_trader_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "Close × individual buy volume ÷ individual buyers.",
              "x-fa": "سرانه‌ی خرید حقیقی: قیمت پایانی ضرب در حجم خرید حقیقی، تقسیم بر تعداد خریداران حقیقی.",
              "x-unit": "rial"
             },
             "individual_sell_per_trader_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "The same for sellers.",
              "x-fa": "سرانه‌ی فروش حقیقی، به همان روش برای فروشندگان.",
              "x-unit": "rial"
             },
             "individual_buyer_power": {
              "type": [
               "number",
               "null"
              ],
              "description": "Buy per trader ÷ sell per trader.",
              "x-fa": "قدرت خریدار حقیقی: سرانه‌ی خرید تقسیم بر سرانه‌ی فروش.",
              "x-unit": "ratio"
             },
             "individual_net_flow_rial": {
              "type": "number",
              "description": "Close × (institutional sell − institutional buy volume). Negative is money leaving.",
              "x-fa": "خالص ورود پول حقیقی: قیمت پایانی ضرب در (حجم فروش حقوقی منهای حجم خرید حقوقی). عدد منفی یعنی خروج پول حقیقی.",
              "x-unit": "rial"
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "date": "2026-10-14",
           "date_jalali": "1405-07-22",
           "trading_state": "trading",
           "close_rial": 4540,
           "last_rial": 4540,
           "previous_close_rial": 4410,
           "volume": 1563050927,
           "value_rial": 7096251208580,
           "trades": 13401,
           "market_cap_rial": 8784900000000000,
           "shares_outstanding": 1935000000000,
           "average_volume_30d": 3418635750.87,
           "individual_buy_volume": 1091991421,
           "individual_sell_volume": 1072498112,
           "institutional_buy_volume": 471059506,
           "institutional_sell_volume": 490552815,
           "individual_buyers": 1517,
           "individual_sellers": 2887,
           "institutional_buyers": 91,
           "institutional_sellers": 16,
           "individual_buy_per_trader_rial": 3268056065.48,
           "individual_sell_per_trader_rial": 1686574793.38,
           "individual_buyer_power": 1.94,
           "individual_net_flow_rial": 88499622860
          }
         ],
         "next_cursor": "WyIyMDI2LTEwLTE0IiwgOTEyMzRd",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "Only days with a session appear.",
      "fa": "فقط روزهایی که معامله داشته‌اند می‌آیند."
     },
     {
      "en": "When a side had no traders the per-trader figures are null, not zero.",
      "fa": "اگر یک طرف معامله‌گری نداشته باشد، سرانه‌ها null است، نه صفر."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest date, inclusive. Jalali (`1404-01-01`) or Gregorian (`2025-03-21`) both work.",
      "x-fa": "قدیمی‌ترین تاریخ، خودش هم حساب می‌شود. هم شمسی (`1404-01-01`) و هم میلادی (`2025-03-21`) پذیرفته می‌شود.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest date, inclusive, in either calendar.",
      "x-fa": "تازه‌ترین تاریخ، خودش هم حساب می‌شود، به هر دو تقویم.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/statements/": {
   "get": {
    "operationId": "statements",
    "tags": [
     "statements"
    ],
    "summary": "Financial statements",
    "description": "Statement lines as the company filed them on Codal: balance sheet, income statement (separate and consolidated) and cash flow. Newest period first.",
    "x-fa": {
     "summary": "صورت‌های مالی",
     "description": "ردیف‌های صورت‌های مالی همان‌طور که شرکت در کدال منتشر کرده: ترازنامه، صورت سود و زیان (جداگانه و تلفیقی) و جریان وجوه نقد، از تازه‌ترین دوره به قدیم."
    },
    "x-cost": 10,
    "x-cost-per-rows": 20,
    "x-kind": "raw",
    "x-page-cap": 2000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "company": {
              "type": "string",
              "description": "Company slug.",
              "x-fa": "شناسه‌ی شرکت."
             },
             "category": {
              "type": "string",
              "description": "Which statement.",
              "x-fa": "کدام صورت مالی."
             },
             "duration": {
              "type": "string",
              "description": "Period label.",
              "x-fa": "برچسب دوره."
             },
             "months": {
              "type": "integer",
              "description": "Months the period covers.",
              "x-fa": "تعداد ماه‌های دوره."
             },
             "fiscal_quarter": {
              "type": [
               "integer",
               "null"
              ],
              "description": "1 to 4 for a quarter, otherwise null.",
              "x-fa": "برای فصل‌ها ۱ تا ۴، وگرنه null."
             },
             "period_end": {
              "type": "string",
              "format": "date",
              "description": "Last day of the period.",
              "x-fa": "آخرین روز دوره."
             },
             "period_end_jalali": {
              "type": "string",
              "description": "The same in Jalali.",
              "x-fa": "همان روز به شمسی."
             },
             "line_slug": {
              "type": "string",
              "description": "Stable line id, the same on every company.",
              "x-fa": "شناسه‌ی ثابت ردیف که در همه‌ی شرکت‌ها یکی است."
             },
             "line_title": {
              "type": "string",
              "description": "Line name in Persian.",
              "x-fa": "نام ردیف."
             },
             "unit": {
              "type": "string",
              "description": "`million_rial`, `rial_per_share` (EPS, DPS) or `percent` (margins).",
              "x-fa": "`million_rial` میلیون ریال، `rial_per_share` ریال برای هر سهم (EPS و DPS)، `percent` درصد (حاشیه‌های سود)."
             },
             "value": {
              "type": "number",
              "description": "The figure, in `unit`.",
              "x-fa": "عدد ردیف، به واحد `unit`."
             },
             "is_forecast": {
              "type": "boolean",
              "description": "A forecast, not a reported figure.",
              "x-fa": "پیش‌بینی است، نه عدد گزارش‌شده."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "company": "foulad",
           "category": "income-statement",
           "duration": "6",
           "months": 6,
           "fiscal_quarter": null,
           "period_end": "2026-09-22",
           "period_end_jalali": "1405-06-31",
           "line_slug": "operating-income",
           "line_title": "درآمدهای عملیاتی",
           "unit": "million_rial",
           "value": 2509422184,
           "is_forecast": false
          },
          {
           "company": "foulad",
           "category": "income-statement",
           "duration": "6",
           "months": 6,
           "fiscal_quarter": null,
           "period_end": "2026-09-22",
           "period_end_jalali": "1405-06-31",
           "line_slug": "eps",
           "line_title": "سود (زیان) خالص هر سهم - ریال",
           "unit": "rial_per_share",
           "value": 306,
           "is_forecast": false
          }
         ],
         "next_cursor": "…",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "Quarters (s-1…s-4) are computed by us from the filed periods; Codal does not file them.",
      "fa": "فصل‌ها (s-1 تا s-4) را ما از دوره‌های تجمعی حساب می‌کنیم. کدال آن‌ها را جدا منتشر نمی‌کند."
     },
     {
      "en": "Margins are computed from the statement's own lines.",
      "fa": "حاشیه‌های سود از ردیف‌های همان صورت مالی حساب شده‌اند."
     },
     {
      "en": "A missing line means it was not filed. Header and empty lines are left out.",
      "fa": "ردیفی که نیامده منتشر نشده است. سرفصل‌ها و ردیف‌های خالی حذف شده‌اند."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "One statement only.",
      "x-fa": "فقط یک صورت مالی.",
      "schema": {
       "type": "string",
       "enum": [
        "balance-sheet",
        "income-statement",
        "income-statement-consolidated",
        "cash-flow"
       ]
      }
     },
     {
      "name": "duration",
      "in": "query",
      "required": false,
      "description": "Period. 3/6/9/12 are filed periods from the start of the fiscal year; s-1 to s-4 single quarters; `filed` and `quarters` select each group.",
      "x-fa": "دوره. ۳، ۶، ۹ و ۱۲ دوره‌های تجمعی از ابتدای سال مالی‌اند و s-1 تا s-4 فصل‌های جداشده. `filed` همه‌ی دوره‌های تجمعی و `quarters` همه‌ی فصل‌ها را می‌دهد.",
      "schema": {
       "type": "string",
       "enum": [
        "3",
        "6",
        "9",
        "12",
        "s-1",
        "s-2",
        "s-3",
        "s-4",
        "filed",
        "quarters"
       ]
      }
     },
     {
      "name": "include_forecasts",
      "in": "query",
      "required": false,
      "description": "Add the company's own forecast rows (income statement only).",
      "x-fa": "ردیف‌های پیش‌بینی خود شرکت را هم می‌آورد (فقط صورت سود و زیان).",
      "schema": {
       "type": "boolean",
       "default": false
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest period end, inclusive, either calendar.",
      "x-fa": "قدیمی‌ترین پایان دوره، به هر دو تقویم.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest period end, inclusive.",
      "x-fa": "تازه‌ترین پایان دوره.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/statements/ttm/": {
   "get": {
    "operationId": "statements_ttm",
    "tags": [
     "statements"
    ],
    "summary": "Trailing twelve months",
    "description": "Built by us from the income statement: trailing-twelve-month sums on each fiscal quarter (`basis=ttm`), or each period with its previous quarter, previous year, high, low and average (`basis=period`).",
    "x-fa": {
     "summary": "چهار فصل اخیر",
     "description": "ساخته‌ی ما از صورت سود و زیان: جمع چهار فصل اخیر در پایان هر فصل مالی (`basis=ttm`)، یا هر دوره کنار فصل قبل، سال قبل، بیشترین، کمترین و میانگین آن (`basis=period`)."
    },
    "x-cost": 15,
    "x-cost-per-rows": 20,
    "x-kind": "processed",
    "x-page-cap": 1000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "company": {
              "type": "string",
              "description": "Company slug.",
              "x-fa": "شناسه‌ی شرکت."
             },
             "category": {
              "type": "string",
              "description": "Which statement.",
              "x-fa": "کدام صورت مالی."
             },
             "basis": {
              "type": "string",
              "description": "`ttm` or `period`.",
              "x-fa": "`ttm` یا `period`."
             },
             "duration": {
              "type": "string",
              "description": "Period label.",
              "x-fa": "برچسب دوره."
             },
             "months": {
              "type": "integer",
              "description": "12 for TTM.",
              "x-fa": "برای TTM عدد ۱۲."
             },
             "fiscal_quarter": {
              "type": [
               "integer",
               "null"
              ],
              "description": "Fiscal quarter the period closes.",
              "x-fa": "فصل مالی پایان دوره."
             },
             "period_end": {
              "type": "string",
              "format": "date",
              "description": "Last day of the period.",
              "x-fa": "آخرین روز دوره."
             },
             "period_end_jalali": {
              "type": "string",
              "description": "Jalali.",
              "x-fa": "به شمسی."
             },
             "line_slug": {
              "type": "string",
              "description": "Line id.",
              "x-fa": "شناسه‌ی ردیف."
             },
             "line_title": {
              "type": "string",
              "description": "Line name.",
              "x-fa": "نام ردیف."
             },
             "unit": {
              "type": "string",
              "description": "As in statements.",
              "x-fa": "مثل صورت‌های مالی."
             },
             "value": {
              "type": "number",
              "description": "TTM sum, or the period's figure.",
              "x-fa": "جمع چهار فصل، یا عدد همان دوره."
             },
             "previous_quarter_value": {
              "type": [
               "number",
               "null"
              ],
              "description": "Quarter before (period basis).",
              "x-fa": "فصل قبل (فقط period)."
             },
             "previous_year_value": {
              "type": [
               "number",
               "null"
              ],
              "description": "Same period a year earlier (period basis).",
              "x-fa": "همان دوره در سال قبل (فقط period)."
             },
             "high_value": {
              "type": [
               "number",
               "null"
              ],
              "description": "Highest value of this line for this period label so far.",
              "x-fa": "بیشترین مقدار این ردیف در همین برچسب دوره تا امروز."
             },
             "high_period_end": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "When the high was.",
              "x-fa": "زمان بیشترین مقدار."
             },
             "high_period_end_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "low_value": {
              "type": [
               "number",
               "null"
              ],
              "description": "Lowest so far.",
              "x-fa": "کمترین مقدار تا امروز."
             },
             "low_period_end": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "When the low was.",
              "x-fa": "زمان کمترین مقدار."
             },
             "low_period_end_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "average_value": {
              "type": [
               "number",
               "null"
              ],
              "description": "Mean of the non-zero periods.",
              "x-fa": "میانگین دوره‌های غیرصفر."
             },
             "average_periods": {
              "type": [
               "integer",
               "null"
              ],
              "description": "How many periods went into the mean.",
              "x-fa": "تعداد دوره‌هایی که در میانگین آمده."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "company": "foulad",
           "category": "income-statement",
           "basis": "ttm",
           "duration": "s-2",
           "months": 12,
           "fiscal_quarter": 2,
           "period_end": "2026-09-22",
           "period_end_jalali": "1405-06-31",
           "line_slug": "operating-income",
           "line_title": "درآمدهای عملیاتی",
           "unit": "million_rial",
           "value": 4569548192,
           "previous_quarter_value": null,
           "previous_year_value": null,
           "high_value": null,
           "high_period_end": null,
           "low_value": null,
           "low_period_end": null,
           "average_value": null,
           "average_periods": null
          }
         ],
         "next_cursor": null,
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "A fixed set of lines is built: operating revenue, gross profit, net profit, margins and EPS.",
      "fa": "فقط ردیف‌های اصلی ساخته می‌شوند: درآمد عملیاتی، سود ناخالص، سود خالص، حاشیه‌های سود و EPS."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "basis",
      "in": "query",
      "required": false,
      "description": "`ttm` or `period`.",
      "x-fa": "`ttm` یا `period`.",
      "schema": {
       "type": "string",
       "enum": [
        "ttm",
        "period"
       ],
       "default": "ttm"
      }
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "Separate or consolidated income statement.",
      "x-fa": "صورت سود و زیان جداگانه یا تلفیقی.",
      "schema": {
       "type": "string",
       "enum": [
        "income-statement",
        "income-statement-consolidated"
       ]
      }
     },
     {
      "name": "duration",
      "in": "query",
      "required": false,
      "description": "Period label. TTM rows only have s-1 to s-4.",
      "x-fa": "برچسب دوره. ردیف‌های TTM فقط s-1 تا s-4 دارند.",
      "schema": {
       "type": "string",
       "enum": [
        "3",
        "6",
        "9",
        "12",
        "s-1",
        "s-2",
        "s-3",
        "s-4",
        "filed",
        "quarters"
       ]
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest date, inclusive. Jalali (`1404-01-01`) or Gregorian (`2025-03-21`) both work.",
      "x-fa": "قدیمی‌ترین تاریخ، خودش هم حساب می‌شود. هم شمسی (`1404-01-01`) و هم میلادی (`2025-03-21`) پذیرفته می‌شود.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest date, inclusive, in either calendar.",
      "x-fa": "تازه‌ترین تاریخ، خودش هم حساب می‌شود، به هر دو تقویم.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/ratios/": {
   "get": {
    "operationId": "ratios",
    "tags": [
     "statements"
    ],
    "summary": "Financial ratios",
    "description": "Valuation, profitability, leverage, activity and cash-flow ratios per calendar day, newest first. Percent fields end in `_pct` and are percents (35.8 means 35.8%).",
    "x-fa": {
     "summary": "نسبت‌های مالی",
     "description": "نسبت‌های ارزش‌گذاری، سودآوری، اهرمی، فعالیت و جریان نقد برای هر روز، از تازه به قدیم. فیلدهایی که به `_pct` ختم می‌شوند درصدند (۳۵٫۸ یعنی ۳۵٫۸ درصد)."
    },
    "x-cost": 15,
    "x-cost-per-rows": 20,
    "x-kind": "processed",
    "x-page-cap": 1000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "company": {
              "type": "string",
              "description": "Company slug.",
              "x-fa": "شناسه‌ی شرکت."
             },
             "date": {
              "type": "string",
              "format": "date",
              "description": "Ratio day (calendar day).",
              "x-fa": "روز محاسبه."
             },
             "date_jalali": {
              "type": "string",
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "price_date": {
              "type": "string",
              "format": "date",
              "description": "Session whose close the price ratios use.",
              "x-fa": "روز معاملاتی که قیمتش در نسبت‌ها آمده."
             },
             "price_date_jalali": {
              "type": "string",
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "close_rial": {
              "type": "number",
              "description": "That close.",
              "x-fa": "همان قیمت پایانی.",
              "x-unit": "rial"
             },
             "period_end": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "Period end of the newest filing used.",
              "x-fa": "پایان دوره‌ی آخرین گزارش."
             },
             "period_end_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "fiscal_quarter": {
              "type": [
               "integer",
               "null"
              ],
              "description": "Which fiscal quarter it closes.",
              "x-fa": "فصل مالی آن گزارش."
             },
             "pe_ttm": {
              "type": [
               "number",
               "null"
              ],
              "description": "Price ÷ TTM EPS.",
              "x-fa": "P/E چهار فصل اخیر: قیمت تقسیم بر EPS چهار فصل اخیر.",
              "x-unit": "ratio"
             },
             "ps_ttm": {
              "type": [
               "number",
               "null"
              ],
              "description": "Market cap ÷ TTM revenue.",
              "x-fa": "P/S چهار فصل اخیر.",
              "x-unit": "ratio"
             },
             "pb": {
              "type": [
               "number",
               "null"
              ],
              "description": "Market cap ÷ equity.",
              "x-fa": "P/B.",
              "x-unit": "ratio"
             },
             "pd_ttm": {
              "type": [
               "number",
               "null"
              ],
              "description": "Price ÷ expected DPS.",
              "x-fa": "P/D: قیمت تقسیم بر سود نقدی مورد انتظار هر سهم.",
              "x-unit": "ratio"
             },
             "peg_ttm": {
              "type": [
               "number",
               "null"
              ],
              "description": "P/E ÷ operating-profit growth %.",
              "x-fa": "PEG: P/E تقسیم بر درصد رشد سود عملیاتی.",
              "x-unit": "ratio"
             },
             "pegy_ttm": {
              "type": [
               "number",
               "null"
              ],
              "description": "PEG with dividend yield added to growth.",
              "x-fa": "PEGY: مثل PEG، با بازده سود نقدی که به رشد اضافه می‌شود.",
              "x-unit": "ratio"
             },
             "eps_ttm_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "TTM EPS.",
              "x-fa": "EPS چهار فصل اخیر.",
              "x-unit": "rial_per_share"
             },
             "operating_revenue_ttm_million_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "TTM operating revenue.",
              "x-fa": "درآمد عملیاتی چهار فصل اخیر.",
              "x-unit": "million_rial"
             },
             "gross_margin_ttm_pct": {
              "type": [
               "number",
               "null"
              ],
              "description": "Gross margin.",
              "x-fa": "حاشیه‌ی سود ناخالص.",
              "x-unit": "percent"
             },
             "net_margin_ttm_pct": {
              "type": [
               "number",
               "null"
              ],
              "description": "Net margin.",
              "x-fa": "حاشیه‌ی سود خالص.",
              "x-unit": "percent"
             },
             "roa_ttm_pct": {
              "type": [
               "number",
               "null"
              ],
              "description": "Return on assets.",
              "x-fa": "بازده دارایی (ROA).",
              "x-unit": "percent"
             },
             "roe_ttm_pct": {
              "type": [
               "number",
               "null"
              ],
              "description": "Return on equity.",
              "x-fa": "بازده حقوق صاحبان سهام (ROE).",
              "x-unit": "percent"
             },
             "debt_to_equity": {
              "type": [
               "number",
               "null"
              ],
              "description": "Total debt ÷ equity.",
              "x-fa": "نسبت بدهی به حقوق صاحبان سهام.",
              "x-unit": "ratio"
             },
             "debt_to_assets_pct": {
              "type": [
               "number",
               "null"
              ],
              "description": "Total debt ÷ assets.",
              "x-fa": "نسبت بدهی به دارایی.",
              "x-unit": "percent"
             },
             "receivable_days_ttm": {
              "type": [
               "number",
               "null"
              ],
              "description": "Collection period.",
              "x-fa": "دوره‌ی وصول مطالبات.",
              "x-unit": "day"
             },
             "inventory_days_ttm": {
              "type": [
               "number",
               "null"
              ],
              "description": "Inventory period.",
              "x-fa": "دوره‌ی گردش موجودی.",
              "x-unit": "day"
             },
             "operating_cash_flow_ttm_million_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "Operating cash flow.",
              "x-fa": "جریان نقد عملیاتی.",
              "x-unit": "million_rial"
             },
             "ocf_to_net_profit_ttm": {
              "type": [
               "number",
               "null"
              ],
              "description": "Operating cash flow ÷ net profit.",
              "x-fa": "نسبت جریان نقد عملیاتی به سود خالص.",
              "x-unit": "ratio"
             },
             "high_close_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "Highest stored close up to this day.",
              "x-fa": "بیشترین قیمت پایانی تا این روز.",
              "x-unit": "rial"
             },
             "low_close_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "Lowest stored close up to this day.",
              "x-fa": "کمترین قیمت پایانی تا این روز.",
              "x-unit": "rial"
             },
             "high_close_date": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "When that high close was.",
              "x-fa": "روز آن بیشترین قیمت."
             },
             "high_close_date_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "low_close_date": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "When that low close was.",
              "x-fa": "روز آن کمترین قیمت."
             },
             "low_close_date_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "pd_period": {
              "type": [
               "number",
               "null"
              ],
              "description": "P/D on the filed period.",
              "x-fa": "P/D روی دوره‌ی گزارش.",
              "x-unit": "ratio"
             },
             "peg_period": {
              "type": [
               "number",
               "null"
              ],
              "description": "PEG on the filed period.",
              "x-fa": "PEG روی دوره‌ی گزارش.",
              "x-unit": "ratio"
             },
             "pegy_period": {
              "type": [
               "number",
               "null"
              ],
              "description": "PEGY on the filed period.",
              "x-fa": "PEGY روی دوره‌ی گزارش.",
              "x-unit": "ratio"
             },
             "roa_period_pct": {
              "type": [
               "number",
               "null"
              ],
              "description": "ROA on the filed period.",
              "x-fa": "ROA روی دوره‌ی گزارش.",
              "x-unit": "percent"
             },
             "roe_period_pct": {
              "type": [
               "number",
               "null"
              ],
              "description": "ROE on the filed period.",
              "x-fa": "ROE روی دوره‌ی گزارش.",
              "x-unit": "percent"
             },
             "receivable_days_period": {
              "type": [
               "number",
               "null"
              ],
              "description": "Collection period, filed period.",
              "x-fa": "دوره‌ی وصول مطالبات در دوره‌ی گزارش.",
              "x-unit": "day"
             },
             "inventory_days_period": {
              "type": [
               "number",
               "null"
              ],
              "description": "Inventory period, filed period.",
              "x-fa": "دوره‌ی گردش موجودی در دوره‌ی گزارش.",
              "x-unit": "day"
             },
             "operating_cash_flow_period_million_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "Operating cash flow, filed period.",
              "x-fa": "جریان نقد عملیاتی دوره‌ی گزارش.",
              "x-unit": "million_rial"
             },
             "ocf_to_net_profit_period": {
              "type": [
               "number",
               "null"
              ],
              "description": "Operating cash flow ÷ net profit, filed period.",
              "x-fa": "نسبت جریان نقد عملیاتی به سود خالص در دوره‌ی گزارش.",
              "x-unit": "ratio"
             },
             "operating_cash_flow_ttm_thousand_usd": {
              "type": [
               "number",
               "null"
              ],
              "description": "TTM operating cash flow, free-market dollar.",
              "x-fa": "جریان نقد عملیاتی چهار فصل اخیر به دلار آزاد.",
              "x-unit": "thousand_usd"
             },
             "operating_cash_flow_ttm_thousand_usd_nima": {
              "type": [
               "number",
               "null"
              ],
              "description": "TTM operating cash flow, NIMA dollar.",
              "x-fa": "جریان نقد عملیاتی چهار فصل اخیر به دلار نیمایی.",
              "x-unit": "thousand_usd"
             },
             "operating_cash_flow_period_thousand_usd": {
              "type": [
               "number",
               "null"
              ],
              "description": "Filed period's operating cash flow, free-market dollar.",
              "x-fa": "جریان نقد عملیاتی دوره‌ی گزارش به دلار آزاد.",
              "x-unit": "thousand_usd"
             },
             "operating_cash_flow_period_thousand_usd_nima": {
              "type": [
               "number",
               "null"
              ],
              "description": "Filed period's operating cash flow, NIMA dollar.",
              "x-fa": "جریان نقد عملیاتی دوره‌ی گزارش به دلار نیمایی.",
              "x-unit": "thousand_usd"
             },
             "ocf_to_net_profit_ttm_usd": {
              "type": [
               "number",
               "null"
              ],
              "description": "Operating cash flow ÷ net profit, both in free-market dollars.",
              "x-fa": "نسبت جریان نقد عملیاتی به سود خالص، هر دو به دلار آزاد.",
              "x-unit": "ratio"
             },
             "ocf_to_net_profit_ttm_usd_nima": {
              "type": [
               "number",
               "null"
              ],
              "description": "Operating cash flow ÷ net profit, both in NIMA dollars.",
              "x-fa": "نسبت جریان نقد عملیاتی به سود خالص، هر دو به دلار نیمایی.",
              "x-unit": "ratio"
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "company": "foulad",
           "date": "2026-10-26",
           "date_jalali": "1405-08-04",
           "price_date": "2026-10-14",
           "close_rial": 4540,
           "period_end": "2026-09-22",
           "fiscal_quarter": 2,
           "pe_ttm": 6.551,
           "ps_ttm": 1.922,
           "pb": 2.344,
           "eps_ttm_rial": 693,
           "gross_margin_ttm_pct": 29.2,
           "net_margin_ttm_pct": 29.3,
           "roa_ttm_pct": 17.2,
           "roe_ttm_pct": 35.8,
           "debt_to_equity": 1.079,
           "debt_to_assets_pct": 51.9,
           "receivable_days_ttm": 153.37,
           "inventory_days_ttm": 135.8
          }
         ],
         "next_cursor": "…",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-fields-note": {
     "en": "Each `_ttm` ratio also has a `_period` twin measured on the filed period alone, not annualised. Cash flow comes in rial and in thousand USD at the free and NIMA rates (`_thousand_usd`, `_thousand_usd_nima`). Every date has a `_jalali` twin.",
     "fa": "هر نسبت `_ttm` یک همتای `_period` هم دارد که فقط روی دوره‌ی گزارش حساب شده و سالانه نشده است. جریان نقد هم به ریال و هم به هزار دلار با نرخ آزاد و نیمایی می‌آید (`_thousand_usd` و `_thousand_usd_nima`). هر تاریخ یک همتای `_jalali` دارد."
    },
    "x-notes": [
     {
      "en": "Rows are calendar days: on a holiday the last close carries over (see `price_date`).",
      "fa": "ردیف‌ها روزهای تقویمی‌اند: در روز تعطیل آخرین قیمت تکرار می‌شود (`price_date` را ببینید)."
     },
     {
      "en": "`_period` ratios are not annualised; don't compare them with `_ttm`.",
      "fa": "نسبت‌های `_period` سالانه نشده‌اند و نباید با `_ttm` مقایسه شوند."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "duration",
      "in": "query",
      "required": false,
      "description": "Fiscal quarter of the newest filing used.",
      "x-fa": "فصل مالی آخرین گزارشی که در محاسبه آمده.",
      "schema": {
       "type": "string",
       "enum": [
        "s-1",
        "s-2",
        "s-3",
        "s-4"
       ]
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest date, inclusive. Jalali (`1404-01-01`) or Gregorian (`2025-03-21`) both work.",
      "x-fa": "قدیمی‌ترین تاریخ، خودش هم حساب می‌شود. هم شمسی (`1404-01-01`) و هم میلادی (`2025-03-21`) پذیرفته می‌شود.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest date, inclusive, in either calendar.",
      "x-fa": "تازه‌ترین تاریخ، خودش هم حساب می‌شود، به هر دو تقویم.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/screener/": {
   "post": {
    "operationId": "screener",
    "tags": [
     "screener"
    ],
    "summary": "Run a filter",
    "description": "Run the same multi-step filter the Fundai screener runs, with every feature open, and get the matching companies with every figure the steps read. Send the body as JSON; retry safely with an `Idempotency-Key`.",
    "x-fa": {
     "summary": "اجرای فیلتر",
     "description": "همان فیلتر چندمرحله‌ای سایت را با همه‌ی امکانات اجرا کنید و شرکت‌هایی را که از فیلتر رد می‌شوند با همه‌ی عددهای هر مرحله بگیرید. بدنه را JSON بفرستید و برای تکرار امن Idempotency-Key بگذارید."
    },
    "x-cost": 25,
    "x-cost-per-rows": 20,
    "x-kind": "processed",
    "x-page-cap": 200,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "slug": {
              "type": "string",
              "description": "Company slug.",
              "x-fa": "شناسه‌ی شرکت."
             },
             "symbol": {
              "type": "string",
              "description": "Symbol.",
              "x-fa": "نماد."
             },
             "name": {
              "type": "string",
              "description": "Company name.",
              "x-fa": "نام شرکت."
             },
             "industry": {
              "type": "object",
              "description": "`{slug, name}`.",
              "x-fa": "صنعت."
             },
             "board": {
              "type": [
               "string",
               "null"
              ],
              "description": "bourse, farabourse, base-yellow, base-orange, base-red, negotiated.",
              "x-fa": "بازار نماد."
             },
             "is_trading_halted": {
              "type": "boolean",
              "description": "Halted today.",
              "x-fa": "امروز متوقف است."
             },
             "figures": {
              "type": "object",
              "description": "Every figure the run read. A step's figure is `step_<n>_<field>`; fixed columns name their unit (`price_rial`, `market_value_billion_toman`). Units for step figures are in `meta.columns`.",
              "x-fa": "همه‌ی عددهای اجرا. عدد هر مرحله `step_<n>_<field>` است و ستون‌های ثابت واحدشان را در نام دارند (`price_rial`، `market_value_billion_toman`). واحد عددهای مرحله در `meta.columns` آمده است."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free. `meta` carries `total_rows`, `total_companies`, `steps` (survivors after each step), `sort`, `columns` (key, English title, format, unit, engine_key) and `money_unit` (billion_toman).",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است. `meta` شامل `total_rows`، `total_companies`، `steps` (تعداد شرکت باقی‌مانده بعد از هر مرحله)، `sort`، `columns` (کلید، عنوان انگلیسی، قالب، واحد و engine_key) و `money_unit` (میلیارد تومان) است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "slug": "gardeshgari",
           "symbol": "وگردش",
           "name": "بانک گردشگری",
           "industry": {
            "slug": "bank",
            "name": "بانک ها و موسسات اعتباری"
           },
           "board": "farabourse",
           "is_trading_halted": false,
           "figures": {
            "step_1_value": 1.676,
            "pe_ttm": 1.676,
            "price_rial": 1730,
            "market_value_billion_toman": 27584.85,
            "eps_rial": 1032
           }
          }
         ],
         "next_cursor": "WzJd",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30",
          "total_rows": 168,
          "total_companies": 168,
          "steps": [
           {
            "step": 1,
            "group": 1,
            "family": "financial-ratio",
            "companies": 168
           }
          ],
          "sort": "pe_ttm",
          "money_unit": "billion_toman"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "Every page costs the run's price; page through with `cursor` inside 5 minutes, while the run is cached.",
      "fa": "هر صفحه هزینه‌ی یک اجرا را دارد. صفحه‌ها را ظرف ۵ دقیقه با `cursor` بگیرید تا نتیجه از حافظه بیاید."
     },
     {
      "en": "The step params are the same as the site's filter builder; build one there, then copy its body.",
      "fa": "پارامترهای هر مرحله همان فیلترساز سایت است. می‌توانید فیلتر را در سایت بسازید و بدنه‌اش را کپی کنید."
     }
    ],
    "parameters": [
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "filters"
        ],
        "properties": {
         "filters": {
          "type": "array",
          "description": "Steps combined with AND: `[{step, params}]`. Families: `financial-ratio`, `monthly`, `income-statement`, `operating-revenue`, `bourse-kala`, `technical`. A step filters when its params carry `operator` (gt, gte, lt, lte, has) and `value`.",
          "x-fa": "مرحله‌ها با «و» کنار هم: `[{step, params}]`. خانواده‌ها: `financial-ratio`، `monthly`، `income-statement`، `operating-revenue`، `bourse-kala` و `technical`. مرحله‌ای که `operator` (gt، gte، lt، lte یا has) و `value` داشته باشد فیلتر می‌کند."
         },
         "groups": {
          "type": "array",
          "description": "Optional OR of AND groups, each a list of steps. When sent, it replaces `filters`.",
          "x-fa": "اختیاری: چند گروه که با «یا» جمع می‌شوند. اگر باشد جای `filters` را می‌گیرد."
         },
         "sort": {
          "type": "string",
          "description": "Engine keys from `meta.columns[].engine_key`, comma separated, `-` for descending.",
          "x-fa": "کلیدهای `meta.columns[].engine_key` با ویرگول، `-` برای نزولی."
         },
         "column_filters": {
          "type": "array",
          "description": "`[{key, min, max}]` on engine keys, in the engine's units.",
          "x-fa": "`[{key, min, max}]` روی کلیدهای موتور، به واحد خود موتور."
         },
         "limit": {
          "type": "integer",
          "description": "Rows per page, 20 by default, up to 200. Every 20 rows (each started block) is one price: 21 to 40 rows cost twice.",
          "x-fa": "ردیف هر صفحه؛ پیش‌فرض ۲۰ ردیف و حداکثر ۲۰۰. هر ۲۰ ردیف (هر دسته‌ی شروع‌شده) یک بار قیمت دارد: ۲۱ تا ۴۰ ردیف دو برابر قیمت دارد."
         },
         "cursor": {
          "type": "string",
          "description": "`next_cursor` of the previous page.",
          "x-fa": "`next_cursor` صفحه‌ی قبل."
         }
        }
       },
       "example": {
        "filters": [
         {
          "step": "financial-ratio",
          "params": {
           "title_slug": "pe_ttm",
           "operator": "lt",
           "value": 8
          }
         }
        ],
        "limit": 2
       }
      }
     }
    }
   }
  },
  "/companies/{company}/sales/": {
   "get": {
    "operationId": "sales",
    "tags": [
     "activity"
    ],
    "summary": "Sales and production",
    "description": "Operating revenue by product from the monthly activity letters and the statements, standardised the way the company page shows it: merged product names and consistent units.",
    "x-fa": {
     "summary": "فروش و تولید",
     "description": "درآمد عملیاتی به تفکیک محصول از گزارش‌های فعالیت ماهانه و صورت‌های مالی، یکسان‌سازی‌شده به همان شکلی که صفحه‌ی شرکت نشان می‌دهد: نام محصولات ادغام‌شده و واحدهای یکدست."
    },
    "x-cost": 15,
    "x-cost-per-rows": 20,
    "x-kind": "processed",
    "x-page-cap": 2000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "product_id": {
              "type": "integer",
              "description": "Product id.",
              "x-fa": "شناسه‌ی محصول."
             },
             "product": {
              "type": "string",
              "description": "Product name in Persian.",
              "x-fa": "نام محصول."
             },
             "product_en": {
              "type": [
               "string",
               "null"
              ],
              "description": "English name.",
              "x-fa": "نام انگلیسی."
             },
             "is_total": {
              "type": "boolean",
              "description": "A sum line (internal, export, total…).",
              "x-fa": "ردیف جمع (داخلی، صادراتی، کل و…)."
             },
             "income_category": {
              "type": "string",
              "description": "`internal_sale`, `export_sale`, `services_revenues`, `discount`, `return_on_sale`…",
              "x-fa": "دسته‌ی درآمد: فروش داخلی، صادراتی، خدمات، تخفیف، برگشت از فروش و…"
             },
             "attr": {
              "type": "string",
              "description": "Which measure the row holds.",
              "x-fa": "شاخصی که این ردیف دارد."
             },
             "period_months": {
              "type": "integer",
              "description": "1, 3, 6, 9 or 12.",
              "x-fa": "۱، ۳، ۶، ۹ یا ۱۲."
             },
             "period_end": {
              "type": "string",
              "format": "date",
              "description": "Last day of the period.",
              "x-fa": "آخرین روز دوره."
             },
             "period_end_jalali": {
              "type": "string",
              "description": "Jalali.",
              "x-fa": "به شمسی."
             },
             "value": {
              "type": [
               "number",
               "null"
              ],
              "description": "The figure.",
              "x-fa": "عدد."
             },
             "unit": {
              "type": [
               "string",
               "null"
              ],
              "description": "Unit as filed, in Persian (تن، هزار تن، عدد…).",
              "x-fa": "واحد به همان شکل که ثبت شده (تن، هزار تن، عدد…)."
             },
             "money_unit": {
              "type": [
               "string",
               "null"
              ],
              "description": "`million_rial` for amounts, `rial_per_unit` for rates (`*_ratio`, per one `unit`), `rial`, or null for physical quantities.",
              "x-fa": "`million_rial` برای مبلغ‌ها، `rial_per_unit` برای نرخ‌ها (ریال برای هر یک `unit`)، `rial`، یا null برای مقدار فیزیکی."
             },
             "standardized": {
              "type": "boolean",
              "description": "A standardisation (merge or unit change) touched this row.",
              "x-fa": "یکسان‌سازی (ادغام یا تغییر واحد) روی این ردیف اثر گذاشته است."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "product_id": 229,
           "product": "محصولات سرد",
           "product_en": "Cold products",
           "is_total": false,
           "income_category": "internal_sale",
           "attr": "sale_price",
           "period_months": 1,
           "period_end": "2026-09-22",
           "period_end_jalali": "1405-06-31",
           "value": 149710887,
           "unit": "میلیون ریال",
           "money_unit": "million_rial",
           "standardized": false
          }
         ],
         "next_cursor": "…",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "Period 1 is that single month, not year to date. 3/6/9/12 are cumulative, as filed.",
      "fa": "دوره‌ی ۱ فقط همان ماه است، نه از ابتدای سال. ۳، ۶، ۹ و ۱۲ تجمعی‌اند، همان‌طور که ثبت شده."
     },
     {
      "en": "Corrections, forecasts and names a merge folded away are left out, as on the site.",
      "fa": "اصلاحات، پیش‌بینی‌ها و نام‌هایی که در ادغام کنار رفته‌اند مثل سایت حذف شده‌اند."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "period",
      "in": "query",
      "required": false,
      "description": "`1` the monthly activity letter (default); `3`, `6`, `9`, `12` cumulative statement periods.",
      "x-fa": "`1` گزارش فعالیت ماهانه (پیش‌فرض)؛ `3`، `6`، `9` و `12` دوره‌های تجمعی صورت‌های مالی.",
      "schema": {
       "type": "string",
       "enum": [
        "1",
        "3",
        "6",
        "9",
        "12"
       ],
       "default": "1"
      }
     },
     {
      "name": "attr",
      "in": "query",
      "required": false,
      "description": "One measure, such as `sale_amount`, `sale_price`, `sale_ratio`, `production_amount`, `cost_sale`.",
      "x-fa": "فقط یک شاخص، مثل `sale_amount` (مقدار فروش)، `sale_price` (مبلغ فروش)، `sale_ratio` (نرخ فروش)، `production_amount` (مقدار تولید) یا `cost_sale` (بهای تمام‌شده).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest period end.",
      "x-fa": "قدیمی‌ترین پایان دوره.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest period end.",
      "x-fa": "تازه‌ترین پایان دوره.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/sales/raw/": {
   "get": {
    "operationId": "sales_raw",
    "tags": [
     "activity"
    ],
    "summary": "Sales and production, raw Codal data",
    "description": "The same rows as `sales`, with every figure as Codal filed it: where a standardisation changed a row, the original value, unit, product name and category are put back and `standardized` is true.",
    "x-fa": {
     "summary": "فروش و تولید، داده‌ی خام کدال",
     "description": "همان ردیف‌های `sales`، با عددهایی که شرکت در کدال ثبت کرده: هر جا یکسان‌سازی ردیفی را تغییر داده، مقدار، واحد، نام محصول و دسته‌ی اصلی برمی‌گردد و `standardized` برابر true است."
    },
    "x-cost": 10,
    "x-cost-per-rows": 20,
    "x-kind": "raw",
    "x-page-cap": 2000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "product_id": {
              "type": "integer",
              "description": "Product id.",
              "x-fa": "شناسه‌ی محصول."
             },
             "product": {
              "type": "string",
              "description": "Product name in Persian.",
              "x-fa": "نام محصول."
             },
             "product_en": {
              "type": [
               "string",
               "null"
              ],
              "description": "English name.",
              "x-fa": "نام انگلیسی."
             },
             "is_total": {
              "type": "boolean",
              "description": "A sum line (internal, export, total…).",
              "x-fa": "ردیف جمع (داخلی، صادراتی، کل و…)."
             },
             "income_category": {
              "type": "string",
              "description": "`internal_sale`, `export_sale`, `services_revenues`, `discount`, `return_on_sale`…",
              "x-fa": "دسته‌ی درآمد: فروش داخلی، صادراتی، خدمات، تخفیف، برگشت از فروش و…"
             },
             "attr": {
              "type": "string",
              "description": "Which measure the row holds.",
              "x-fa": "شاخصی که این ردیف دارد."
             },
             "period_months": {
              "type": "integer",
              "description": "1, 3, 6, 9 or 12.",
              "x-fa": "۱، ۳، ۶، ۹ یا ۱۲."
             },
             "period_end": {
              "type": "string",
              "format": "date",
              "description": "Last day of the period.",
              "x-fa": "آخرین روز دوره."
             },
             "period_end_jalali": {
              "type": "string",
              "description": "Jalali.",
              "x-fa": "به شمسی."
             },
             "value": {
              "type": [
               "number",
               "null"
              ],
              "description": "The figure.",
              "x-fa": "عدد."
             },
             "unit": {
              "type": [
               "string",
               "null"
              ],
              "description": "Unit as filed, in Persian (تن، هزار تن، عدد…).",
              "x-fa": "واحد به همان شکل که ثبت شده (تن، هزار تن، عدد…)."
             },
             "money_unit": {
              "type": [
               "string",
               "null"
              ],
              "description": "`million_rial` for amounts, `rial_per_unit` for rates (`*_ratio`, per one `unit`), `rial`, or null for physical quantities.",
              "x-fa": "`million_rial` برای مبلغ‌ها، `rial_per_unit` برای نرخ‌ها (ریال برای هر یک `unit`)، `rial`، یا null برای مقدار فیزیکی."
             },
             "standardized": {
              "type": "boolean",
              "description": "A standardisation (merge or unit change) touched this row.",
              "x-fa": "یکسان‌سازی (ادغام یا تغییر واحد) روی این ردیف اثر گذاشته است."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "product_id": 229,
           "product": "محصولات سرد",
           "product_en": "Cold products",
           "is_total": false,
           "income_category": "internal_sale",
           "attr": "sale_amount",
           "period_months": 1,
           "period_end": "2026-09-22",
           "period_end_jalali": "1405-06-31",
           "value": 138,
           "unit": "هزار تن",
           "money_unit": null,
           "standardized": false
          }
         ],
         "next_cursor": "…",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "A row a merge dropped as a duplicate cannot be shown.",
      "fa": "ردیفی را که در ادغام به‌عنوان تکراری حذف شده نمی‌توانیم نشان دهیم."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "period",
      "in": "query",
      "required": false,
      "description": "`1` the monthly activity letter (default); `3`, `6`, `9`, `12` cumulative statement periods.",
      "x-fa": "`1` گزارش فعالیت ماهانه (پیش‌فرض)؛ `3`، `6`، `9` و `12` دوره‌های تجمعی صورت‌های مالی.",
      "schema": {
       "type": "string",
       "enum": [
        "1",
        "3",
        "6",
        "9",
        "12"
       ],
       "default": "1"
      }
     },
     {
      "name": "attr",
      "in": "query",
      "required": false,
      "description": "One measure, such as `sale_amount`, `sale_price`, `sale_ratio`, `production_amount`, `cost_sale`.",
      "x-fa": "فقط یک شاخص، مثل `sale_amount` (مقدار فروش)، `sale_price` (مبلغ فروش)، `sale_ratio` (نرخ فروش)، `production_amount` (مقدار تولید) یا `cost_sale` (بهای تمام‌شده).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest period end.",
      "x-fa": "قدیمی‌ترین پایان دوره.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest period end.",
      "x-fa": "تازه‌ترین پایان دوره.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/commodity-trades/": {
   "get": {
    "operationId": "commodity_trades",
    "tags": [
     "activity"
    ],
    "summary": "Commodity exchange trades",
    "description": "Every trade of the company's products on the Iran Mercantile Exchange (IME), newest first, as IME published it.",
    "x-fa": {
     "summary": "معاملات بورس کالا",
     "description": "همه‌ی معاملات محصولات شرکت در بورس کالای ایران، از تازه به قدیم، همان‌طور که بورس کالا منتشر کرده."
    },
    "x-cost": 10,
    "x-cost-per-rows": 20,
    "x-kind": "raw",
    "x-page-cap": 2000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string",
              "description": "IME's own trade id.",
              "x-fa": "شناسه‌ی معامله در بورس کالا."
             },
             "date": {
              "type": "string",
              "format": "date",
              "description": "Trade date.",
              "x-fa": "تاریخ معامله."
             },
             "date_jalali": {
              "type": "string",
              "description": "Jalali.",
              "x-fa": "به شمسی."
             },
             "product": {
              "type": "string",
              "description": "Product name.",
              "x-fa": "نام محصول."
             },
             "product_en": {
              "type": [
               "string",
               "null"
              ],
              "description": "English name.",
              "x-fa": "نام انگلیسی."
             },
             "product_symbol": {
              "type": "string",
              "description": "IME symbol.",
              "x-fa": "نماد محصول در بورس کالا."
             },
             "income_category": {
              "type": "string",
              "description": "`internal_sale` or `export_sale`.",
              "x-fa": "فروش داخلی یا صادراتی."
             },
             "contract_type": {
              "type": "string",
              "description": "`cash`, `credit`, `self` (سلف), `cash_dollar`, `cash_export`…",
              "x-fa": "نوع قرارداد: نقدی، نسیه، سلف، دلاری، صادراتی و…"
             },
             "currency": {
              "type": "string",
              "description": "`IRR`, `USD`, `USD_FREE`, `EUR`, `AED`…",
              "x-fa": "ارز معامله."
             },
             "unit": {
              "type": "string",
              "description": "Trading unit as filed (تن، عدد…).",
              "x-fa": "واحد معامله به همان شکل ثبت‌شده."
             },
             "supply": {
              "type": "number",
              "description": "Volume offered, in `unit`.",
              "x-fa": "عرضه، به واحد `unit`."
             },
             "demand": {
              "type": "number",
              "description": "Volume demanded.",
              "x-fa": "تقاضا."
             },
             "quantity": {
              "type": "number",
              "description": "Volume traded.",
              "x-fa": "حجم معامله‌شده."
             },
             "base_price": {
              "type": "number",
              "description": "Base offer price.",
              "x-fa": "قیمت پایه‌ی عرضه."
             },
             "min_price": {
              "type": "number",
              "description": "Lowest price.",
              "x-fa": "کمترین قیمت."
             },
             "max_price": {
              "type": "number",
              "description": "Highest price.",
              "x-fa": "بیشترین قیمت."
             },
             "price": {
              "type": "number",
              "description": "Weighted-average price. Rial per kg for ton-traded rial trades, per item for count-traded; in `currency` per `unit` for currency trades.",
              "x-fa": "قیمت میانگین وزنی. برای معامله‌ی ریالی محصولی که به تن معامله می‌شود ریال برای هر کیلوگرم، برای کالای شمارشی ریال برای هر عدد، و برای معامله‌ی ارزی به همان ارز برای هر `unit`."
             },
             "value_thousand_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "Trade value of a rial trade.",
              "x-fa": "ارزش معامله‌ی ریالی.",
              "x-unit": "thousand_rial"
             },
             "value_in_currency": {
              "type": [
               "number",
               "null"
              ],
              "description": "Trade value of a currency trade, in `currency`.",
              "x-fa": "ارزش معامله‌ی ارزی، به همان ارز."
             },
             "delivery_date": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "Delivery date.",
              "x-fa": "تاریخ تحویل."
             },
             "delivery_date_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "settlement_date": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "Settlement date.",
              "x-fa": "تاریخ تسویه."
             },
             "settlement_date_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "warehouse": {
              "type": [
               "string",
               "null"
              ],
              "description": "Delivery warehouse.",
              "x-fa": "انبار تحویل."
             },
             "settlement": {
              "type": [
               "string",
               "null"
              ],
              "description": "Settlement terms, Persian as filed.",
              "x-fa": "شرایط تسویه."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "id": "r685122",
           "date": "2026-10-11",
           "date_jalali": "1405-07-19",
           "product": "آرگون",
           "product_en": "Argon",
           "product_symbol": "MSC-ARGAB-00",
           "income_category": "internal_sale",
           "contract_type": "self",
           "currency": "IRR",
           "unit": "تن",
           "supply": 200,
           "demand": 460,
           "quantity": 200,
           "base_price": 321300,
           "min_price": 621899,
           "max_price": 648999,
           "price": 628847,
           "value_thousand_rial": 125769400,
           "value_in_currency": null,
           "delivery_date": "2026-11-09",
           "settlement_date": null,
           "warehouse": "انبار کارخانه",
           "settlement": "نقدی"
          }
         ],
         "next_cursor": "…",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "Offers with no trade are left out. Nothing is converted to rial: this is the raw dataset.",
      "fa": "عرضه‌های بدون معامله حذف شده‌اند. چیزی به ریال تبدیل نشده، چون این داده‌ی خام است."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest date, inclusive. Jalali (`1404-01-01`) or Gregorian (`2025-03-21`) both work.",
      "x-fa": "قدیمی‌ترین تاریخ، خودش هم حساب می‌شود. هم شمسی (`1404-01-01`) و هم میلادی (`2025-03-21`) پذیرفته می‌شود.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest date, inclusive, in either calendar.",
      "x-fa": "تازه‌ترین تاریخ، خودش هم حساب می‌شود، به هر دو تقویم.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/dividends/": {
   "get": {
    "operationId": "dividends",
    "tags": [
     "corporate"
    ],
    "summary": "Dividends",
    "description": "One row per fiscal year: the annual meeting, the dividend per share it approved, and when it is paid to shareholders.",
    "x-fa": {
     "summary": "سود نقدی",
     "description": "برای هر سال مالی یک ردیف: مجمع عادی سالانه، سود نقدی هر سهم که تصویب کرده و زمان پرداخت آن به سهام‌داران."
    },
    "x-cost": 15,
    "x-cost-per-rows": 20,
    "x-kind": "processed",
    "x-page-cap": 100,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "fiscal_year_end": {
              "type": "string",
              "format": "date",
              "description": "End of the fiscal year the meeting decides on.",
              "x-fa": "پایان سال مالی که مجمع درباره‌اش تصمیم می‌گیرد."
             },
             "fiscal_year_end_jalali": {
              "type": "string",
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "meeting_date": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "Meeting date.",
              "x-fa": "تاریخ مجمع."
             },
             "meeting_date_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "meeting_time": {
              "type": [
               "string",
               "null"
              ],
              "description": "HH:MM, Tehran time.",
              "x-fa": "ساعت مجمع به وقت تهران."
             },
             "meeting_url": {
              "type": [
               "string",
               "null"
              ],
              "description": "Codal letter of the invitation.",
              "x-fa": "نامه‌ی دعوت به مجمع در کدال."
             },
             "payment_from": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "Start of the payment window to individual shareholders.",
              "x-fa": "شروع پرداخت سود به سهام‌داران حقیقی."
             },
             "payment_from_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "payment_to": {
              "type": [
               "string",
               "null"
              ],
              "format": "date",
              "description": "End of the window. Equal to `payment_from` when one day is named.",
              "x-fa": "پایان پرداخت. اگر یک روز اعلام شده باشد با `payment_from` یکی است."
             },
             "payment_to_jalali": {
              "type": [
               "string",
               "null"
              ],
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "payment_text": {
              "type": [
               "string",
               "null"
              ],
              "description": "The schedule letter's own words, Persian.",
              "x-fa": "عبارت خود نامه‌ی زمان‌بندی."
             },
             "payment_estimated": {
              "type": "boolean",
              "description": "The letter names no single day.",
              "x-fa": "نامه روز مشخصی نگفته است."
             },
             "schedule_url": {
              "type": [
               "string",
               "null"
              ],
              "description": "Codal letter of the payment schedule.",
              "x-fa": "نامه‌ی زمان‌بندی پرداخت در کدال."
             },
             "dividend_per_share_rial": {
              "type": [
               "integer",
               "null"
              ],
              "description": "Approved dividend per share.",
              "x-fa": "سود نقدی هر سهم.",
              "x-unit": "rial_per_share"
             },
             "days_to_payment": {
              "type": [
               "integer",
               "null"
              ],
              "description": "Days from the meeting to the payment.",
              "x-fa": "فاصله‌ی مجمع تا پرداخت، به روز."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "fiscal_year_end": "2026-03-20",
           "fiscal_year_end_jalali": "1404-12-29",
           "meeting_date": "2026-07-20",
           "meeting_time": "09:00",
           "payment_from": "2026-09-08",
           "payment_to": "2026-09-08",
           "payment_text": "۱۴۰۵/۰۶/۱۷",
           "payment_estimated": false,
           "dividend_per_share_rial": 55,
           "days_to_payment": 50
          }
         ],
         "next_cursor": "…",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "Only readings we are confident in are served, as on the site.",
      "fa": "فقط خوانش‌هایی می‌آیند که از درستی‌شان مطمئنیم، مثل سایت."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest fiscal year end.",
      "x-fa": "قدیمی‌ترین پایان سال مالی.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest fiscal year end.",
      "x-fa": "تازه‌ترین پایان سال مالی.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/letters/": {
   "get": {
    "operationId": "letters",
    "tags": [
     "corporate"
    ],
    "summary": "Codal report letters",
    "description": "The financial-report letters the figures are read from: monthly activity reports and interim and annual statements, with links to the letter, its PDF and Excel export.",
    "x-fa": {
     "summary": "گزارش‌های کدال",
     "description": "نامه‌های گزارش مالی که عددها از آن‌ها خوانده می‌شود: گزارش فعالیت ماهانه و صورت‌های مالی میان‌دوره‌ای و سالانه، با لینک نامه، PDF و خروجی اکسل."
    },
    "x-cost": 10,
    "x-cost-per-rows": 20,
    "x-kind": "raw",
    "x-page-cap": 500,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer",
              "description": "Our id.",
              "x-fa": "شناسه."
             },
             "title": {
              "type": "string",
              "description": "Codal's title.",
              "x-fa": "عنوان نامه در کدال."
             },
             "period_months": {
              "type": "integer",
              "description": "1, 3, 6, 9 or 12.",
              "x-fa": "طول دوره به ماه."
             },
             "period_end": {
              "type": "string",
              "format": "date",
              "description": "End of the reported period.",
              "x-fa": "پایان دوره‌ی گزارش."
             },
             "period_end_jalali": {
              "type": "string",
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "published_at": {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 with Tehran offset.",
              "x-fa": "زمان انتشار."
             },
             "published_at_jalali": {
              "type": "string",
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "is_audited": {
              "type": "boolean",
              "description": "Audited.",
              "x-fa": "حسابرسی‌شده."
             },
             "is_consolidated": {
              "type": "boolean",
              "description": "Consolidated (تلفیقی).",
              "x-fa": "تلفیقی."
             },
             "is_correction": {
              "type": "boolean",
              "description": "A correction (اصلاحیه).",
              "x-fa": "اصلاحیه."
             },
             "url": {
              "type": "string",
              "description": "The Codal letter.",
              "x-fa": "لینک نامه."
             },
             "attachment_url": {
              "type": [
               "string",
               "null"
              ],
              "description": "Attachments.",
              "x-fa": "پیوست‌ها."
             },
             "pdf_url": {
              "type": [
               "string",
               "null"
              ],
              "description": "PDF.",
              "x-fa": "فایل PDF."
             },
             "excel_url": {
              "type": [
               "string",
               "null"
              ],
              "description": "Excel export.",
              "x-fa": "خروجی اکسل."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "id": 92671,
           "title": "اطلاعات و صورت‌های مالی میاندوره‌ای دوره ۶ ماهه منتهی به ۱۴۰۵/۰۶/۳۱ (حسابرسی نشده)",
           "period_months": 6,
           "period_end": "2026-09-22",
           "published_at": "2026-10-22T14:37:13+03:30",
           "is_audited": false,
           "is_consolidated": false,
           "is_correction": false,
           "url": "https://www.codal.ir/Reports/Decision.aspx?LetterSerial=…"
          }
         ],
         "next_cursor": "…",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-notes": [
     {
      "en": "A period filed more than once (unaudited, audited, corrected) shows every filing.",
      "fa": "دوره‌ای که چند بار منتشر شده (حسابرسی‌نشده، حسابرسی‌شده، اصلاحیه) همه‌ی نسخه‌هایش را دارد."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "period",
      "in": "query",
      "required": false,
      "description": "1, 3, 6, 9 or 12.",
      "x-fa": "۱، ۳، ۶، ۹ یا ۱۲.",
      "schema": {
       "type": "string",
       "enum": [
        "1",
        "3",
        "6",
        "9",
        "12"
       ]
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest publish day.",
      "x-fa": "قدیمی‌ترین روز انتشار.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest publish day.",
      "x-fa": "تازه‌ترین روز انتشار.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  },
  "/companies/{company}/portfolio/": {
   "get": {
    "operationId": "portfolio",
    "tags": [
     "corporate"
    ],
    "summary": "Fund and holding portfolios",
    "description": "What a fund or an investment holding owns, one row per investee per monthly report. Without a date you get the newest report. A company that is neither answers an empty list.",
    "x-fa": {
     "summary": "پرتفوی صندوق‌ها و شرکت‌های سرمایه‌گذاری",
     "description": "دارایی‌های یک صندوق یا شرکت سرمایه‌گذاری، برای هر شرکت سرمایه‌پذیر در هر گزارش ماهانه یک ردیف. بدون تاریخ، تازه‌ترین گزارش می‌آید. شرکتی که هیچ‌کدام نباشد فهرست خالی می‌گیرد."
    },
    "x-cost": 20,
    "x-cost-per-rows": 20,
    "x-kind": "processed",
    "x-page-cap": 1000,
    "responses": {
     "200": {
      "description": "OK",
      "headers": {
       "X-Request-Id": {
        "$ref": "#/components/headers/X-Request-Id"
       },
       "X-Credits-Charged": {
        "$ref": "#/components/headers/X-Credits-Charged"
       },
       "X-Credits-Remaining": {
        "$ref": "#/components/headers/X-Credits-Remaining"
       },
       "X-Credits-Cost": {
        "$ref": "#/components/headers/X-Credits-Cost"
       },
       "X-Credits-Per-Rows": {
        "$ref": "#/components/headers/X-Credits-Per-Rows"
       },
       "X-RateLimit-Limit": {
        "$ref": "#/components/headers/X-RateLimit-Limit"
       },
       "X-RateLimit-Remaining": {
        "$ref": "#/components/headers/X-RateLimit-Remaining"
       },
       "X-RateLimit-Reset": {
        "$ref": "#/components/headers/X-RateLimit-Reset"
       },
       "X-Replayed": {
        "$ref": "#/components/headers/X-Replayed"
       },
       "X-Sandbox": {
        "$ref": "#/components/headers/X-Sandbox"
       },
       "ETag": {
        "$ref": "#/components/headers/ETag"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "portfolio_type": {
              "type": "string",
              "description": "`fund` or `holding`.",
              "x-fa": "صندوق یا شرکت سرمایه‌گذاری."
             },
             "report_date": {
              "type": "string",
              "format": "date",
              "description": "Month end reported.",
              "x-fa": "پایان ماه گزارش."
             },
             "report_date_jalali": {
              "type": "string",
              "description": "The same date in the Jalali calendar.",
              "x-fa": "همان تاریخ به شمسی."
             },
             "letter_url": {
              "type": "string",
              "description": "The Codal letter.",
              "x-fa": "نامه‌ی کدال."
             },
             "letter_tracing_no": {
              "type": "integer",
              "description": "Codal tracing number.",
              "x-fa": "شماره‌ی پیگیری کدال."
             },
             "name": {
              "type": [
               "string",
               "null"
              ],
              "description": "Investee as written in the sheet.",
              "x-fa": "نام شرکت سرمایه‌پذیر به همان شکل گزارش."
             },
             "company": {
              "type": [
               "object",
               "null"
              ],
              "description": "`{slug, symbol}` of the listed company, if linked.",
              "x-fa": "شرکت بورسی متناظر، اگر پیدا شده باشد."
             },
             "closing_quantity": {
              "type": [
               "number",
               "null"
              ],
              "description": "Shares held at month end.",
              "x-fa": "تعداد سهام در پایان ماه.",
              "x-unit": "share"
             },
             "closing_cost_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "Cost at month end.",
              "x-fa": "بهای تمام‌شده در پایان ماه.",
              "x-unit": "rial"
             },
             "closing_value_rial": {
              "type": [
               "number",
               "null"
              ],
              "description": "Value at month end (net sale value for a fund, market value for a holding).",
              "x-fa": "ارزش در پایان ماه (خالص ارزش فروش برای صندوق، ارزش بازار برای شرکت سرمایه‌گذاری).",
              "x-unit": "rial"
             },
             "ownership_percent": {
              "type": [
               "number",
               "null"
              ],
              "description": "Holding only: share of the investee owned.",
              "x-fa": "فقط شرکت سرمایه‌گذاری: درصد مالکیت.",
              "x-unit": "percent"
             },
             "segment": {
              "type": [
               "string",
               "null"
              ],
              "description": "Holding only: `exchange`, `base` or `unlisted`.",
              "x-fa": "فقط شرکت سرمایه‌گذاری: بورسی، بازار پایه یا غیربورسی."
             }
            }
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ],
           "description": "Send back as `cursor` for the next page; null on the last."
          },
          "meta": {
           "type": "object",
           "description": "`updated_at`: when the data behind the answer last changed. An empty list also has `empty`: `no-data` (no rows of this dataset for the company) or `no-match` (none fit the filters); it is free.",
           "x-fa": "`updated_at`: زمان آخرین به‌روزرسانی داده‌ی این پاسخ. فهرست خالی `empty` هم دارد: `no-data` (این داده برای این شرکت نیست) یا `no-match` (ردیفی با فیلترها جور نشد)؛ پاسخ خالی رایگان است.",
           "properties": {
            "updated_at": {
             "type": [
              "string",
              "null"
             ],
             "format": "date-time"
            },
            "empty": {
             "type": "string",
             "enum": [
              "no-data",
              "no-match"
             ]
            }
           }
          }
         }
        },
        "example": {
         "data": [
          {
           "portfolio_type": "fund",
           "report_date": "2026-09-22",
           "letter_tracing_no": 1606387,
           "name": "آريان كيميا تك",
           "company": {
            "slug": "kimia-tech",
            "symbol": "کیمیاتک"
           },
           "closing_quantity": 1116173,
           "closing_price_rial": 19450,
           "closing_cost_rial": 8887705531,
           "closing_value_rial": 21541749914
          }
         ],
         "next_cursor": "…",
         "meta": {
          "updated_at": "2026-11-09T08:30:00+03:30"
         }
        }
       }
      }
     },
     "default": {
      "$ref": "#/components/responses/Error"
     }
    },
    "x-fields-note": {
     "en": "A fund row also has opening, bought and sold quantity, cost and amount (`opening_*`, `bought_*`, `sold_*`) and `closing_price_rial`. A holding row has `opening_*`, the month's `change_*`, `capital_rial`, `par_value_rial`, `is_rights` and `cost_per_share_rial`. All money is in rial.",
     "fa": "ردیف صندوق تعداد، بهای تمام‌شده و مبلغ ابتدای دوره، خرید و فروش را هم دارد (`opening_*`، `bought_*`، `sold_*`) و `closing_price_rial`. ردیف شرکت سرمایه‌گذاری `opening_*`، تغییر ماه (`change_*`)، `capital_rial`، `par_value_rial`، `is_rights` و `cost_per_share_rial` را دارد. همه‌ی مبلغ‌ها به ریال است."
    },
    "x-notes": [
     {
      "en": "Values are as filed; only the stock sheet is covered.",
      "fa": "مقدارها همان‌طور که گزارش شده‌اند. فقط بخش سهام پوشش داده می‌شود."
     }
    ],
    "parameters": [
     {
      "name": "company",
      "in": "path",
      "required": true,
      "description": "The company's `slug` from /companies/, or its symbol (فولاد). Symbols are matched in every spelling Codal and TSETMC use.",
      "x-fa": "مقدار `slug` شرکت از فهرست /companies/، یا نماد آن (فولاد). نماد با هر املایی که کدال و سایت بورس می‌نویسند پیدا می‌شود.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "report_date",
      "in": "query",
      "required": false,
      "description": "Exactly this month's report.",
      "x-fa": "فقط گزارش همین ماه.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Earliest date, inclusive. Jalali (`1404-01-01`) or Gregorian (`2025-03-21`) both work.",
      "x-fa": "قدیمی‌ترین تاریخ، خودش هم حساب می‌شود. هم شمسی (`1404-01-01`) و هم میلادی (`2025-03-21`) پذیرفته می‌شود.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "Latest date, inclusive, in either calendar.",
      "x-fa": "تازه‌ترین تاریخ، خودش هم حساب می‌شود، به هر دو تقویم.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page. Defaults to one priced block (`per_rows`: 30 for daily trading, 20 for most datasets). A page pays once per started block, so 21 statement rows cost twice. Above the dataset's cap is a 400.",
      "x-fa": "تعداد ردیف هر صفحه. پیش‌فرض یک دسته‌ی قیمت است (`per_rows`: برای معاملات روزانه ۳۰ و برای بیشتر داده‌ها ۲۰). هر دسته‌ی شروع‌شده یک بار حساب می‌شود، پس ۲۱ ردیف صورت مالی دو برابر قیمت دارد. بیشتر از سقف همان داده خطای ۴۰۰ می‌گیرد.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "The `next_cursor` of the previous page, sent back as it came. Leave it out for the first page.",
      "x-fa": "مقدار `next_cursor` صفحه‌ی قبل را همان‌طور که آمده بفرستید. برای صفحه‌ی اول نفرستید.",
      "schema": {
       "type": "string"
      }
     },
     {
      "$ref": "#/components/parameters/IdempotencyKey"
     }
    ]
   }
  }
 },
 "x-errors": [
  {
   "status": 400,
   "detail": "validation-error",
   "description": "A parameter is wrong; `errors` names it.",
   "x-fa": "یکی از پارامترها اشتباه است و `errors` نامش را می‌گوید."
  },
  {
   "status": 400,
   "detail": "api-cursor-invalid",
   "description": "Send `next_cursor` back as it came.",
   "x-fa": "`next_cursor` را همان‌طور که آمده برگردانید."
  },
  {
   "status": 400,
   "detail": "api-idempotency-key-invalid",
   "description": "`Idempotency-Key` is over 100 characters.",
   "x-fa": "`Idempotency-Key` بیشتر از ۱۰۰ کاراکتر است."
  },
  {
   "status": 401,
   "detail": "api-key-missing",
   "description": "No key in `Authorization` or `X-API-Key`.",
   "x-fa": "کلید در `Authorization` یا `X-API-Key` فرستاده نشده است."
  },
  {
   "status": 401,
   "detail": "api-key-invalid",
   "description": "Unknown, disabled or expired key.",
   "x-fa": "کلید شناخته نشد، یا غیرفعال یا منقضی شده است."
  },
  {
   "status": 402,
   "detail": "insufficient-credit",
   "description": "Not enough credit for this request. Nothing was charged.",
   "x-fa": "اعتبار برای این درخواست کافی نیست. چیزی کم نشد."
  },
  {
   "status": 403,
   "detail": "api-client-suspended",
   "description": "Your API access is suspended.",
   "x-fa": "دسترسی API شما فعلاً بسته شده است."
  },
  {
   "status": 403,
   "detail": "api-origin-not-allowed",
   "description": "Called from a browser origin not on your list.",
   "x-fa": "درخواست از مرورگری آمده که در فهرست مجاز شما نیست."
  },
  {
   "status": 403,
   "detail": "api-dataset-unavailable",
   "description": "This dataset is not open to your account.",
   "x-fa": "این داده برای حساب شما باز نیست."
  },
  {
   "status": 404,
   "detail": "company-not-found",
   "description": "No listed company with that slug or symbol.",
   "x-fa": "شرکتی با این شناسه یا نماد پیدا نشد."
  },
  {
   "status": 409,
   "detail": "api-idempotency-key-reused",
   "description": "This `Idempotency-Key` was used for a different request.",
   "x-fa": "این `Idempotency-Key` برای درخواست دیگری به کار رفته است."
  },
  {
   "status": 409,
   "detail": "api-idempotency-in-progress",
   "description": "The first request with this `Idempotency-Key` is still running.",
   "x-fa": "درخواست اول با همین `Idempotency-Key` هنوز تمام نشده است."
  },
  {
   "status": 403,
   "detail": "api-company-cap",
   "description": "This month's company cap is reached: reading a new company waits for next month (Jalali); companies already read this month stay open. Wider access is a contract.",
   "x-fa": "سقف شرکت‌های این ماه پر شده است: شرکت تازه از ماه بعد (شمسی) باز می‌شود و شرکت‌هایی که این ماه خوانده‌اید باز می‌مانند. دسترسی بیشتر با قرارداد سازمانی است."
  },
  {
   "status": 403,
   "detail": "api-sandbox-needs-purchase",
   "description": "Test keys work once the account has bought credit; until then, try the API with the trial credits.",
   "x-fa": "کلید آزمایشی بعد از اولین خرید اعتبار کار می‌کند؛ تا آن موقع API را با اعتبار هدیه امتحان کنید."
  },
  {
   "status": 429,
   "detail": "api-rate-limited",
   "description": "Per-minute limit; wait `Retry-After` seconds.",
   "x-fa": "سقف دقیقه پر شد؛ به اندازه‌ی `Retry-After` صبر کنید."
  },
  {
   "status": 429,
   "detail": "api-daily-limit",
   "description": "Daily limit; resets at midnight Tehran time.",
   "x-fa": "سقف روزانه پر شد؛ نیمه‌شب به وقت تهران دوباره باز می‌شود."
  },
  {
   "status": 429,
   "detail": "api-too-many-parallel",
   "description": "Too many requests in flight at once.",
   "x-fa": "درخواست‌های هم‌زمان شما به سقف رسیده است."
  },
  {
   "status": 503,
   "detail": "api-busy",
   "description": "The API as a whole is at its ceiling; retry shortly.",
   "x-fa": "کل API به سقفش رسیده؛ کمی بعد دوباره بفرستید."
  },
  {
   "status": 503,
   "detail": "api-paused",
   "description": "The API is paused for maintenance.",
   "x-fa": "API برای به‌روزرسانی موقتاً متوقف است."
  }
 ],
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "Authorization: Bearer fai-api_… (or X-API-Key). Server-side only."
   }
  },
  "parameters": {
   "IdempotencyKey": {
    "name": "Idempotency-Key",
    "in": "header",
    "required": false,
    "description": "Any unique string up to 100 characters. A retry with the same key and the same request returns the first answer and is not charged again, for idempotency_hours (24 by default).",
    "x-fa": "هر رشته‌ی یکتا تا ۱۰۰ کاراکتر. اگر همان درخواست را با همین کلید دوباره بفرستید، همان پاسخ اول برمی‌گردد و دوباره هزینه‌ای کم نمی‌شود (تا ۲۴ ساعت).",
    "schema": {
     "type": "string",
     "maxLength": 100
    }
   }
  },
  "headers": {
   "X-Request-Id": {
    "description": "Quote it to support to ask about one call.",
    "x-fa": "برای پیگیری یک درخواست، این شناسه را به پشتیبانی بدهید.",
    "schema": {
     "type": "string"
    }
   },
   "X-Credits-Charged": {
    "description": "Credits this request cost (0 when free).",
    "x-fa": "اعتباری که همین درخواست کم کرد (برای درخواست رایگان صفر).",
    "schema": {
     "type": "string"
    }
   },
   "X-Credits-Remaining": {
    "description": "Your balance after this request.",
    "x-fa": "اعتبار باقی‌مانده بعد از این درخواست.",
    "schema": {
     "type": "string"
    }
   },
   "X-Credits-Cost": {
    "description": "The dataset's price for each block of `X-Credits-Per-Rows` rows.",
    "x-fa": "قیمت این داده برای هر `X-Credits-Per-Rows` ردیف.",
    "schema": {
     "type": "string"
    }
   },
   "X-Credits-Per-Rows": {
    "description": "Rows one price buys: a call pays once per started block of them.",
    "x-fa": "تعداد ردیفی که یک بار قیمت می‌خرد: هر بلوکِ شروع‌شده یک بار حساب می‌شود.",
    "schema": {
     "type": "string"
    }
   },
   "X-RateLimit-Limit": {
    "description": "Requests allowed this minute.",
    "x-fa": "تعداد درخواست مجاز در این دقیقه.",
    "schema": {
     "type": "string"
    }
   },
   "X-RateLimit-Remaining": {
    "description": "Requests left this minute.",
    "x-fa": "درخواست باقی‌مانده در این دقیقه.",
    "schema": {
     "type": "string"
    }
   },
   "X-RateLimit-Reset": {
    "description": "Seconds until the minute resets.",
    "x-fa": "ثانیه تا شروع دقیقه‌ی بعد.",
    "schema": {
     "type": "string"
    }
   },
   "X-Replayed": {
    "description": "`true` when the answer came from a free repeat or an Idempotency-Key replay.",
    "x-fa": "وقتی پاسخ از تکرار رایگان یا Idempotency-Key آمده باشد `true` است.",
    "schema": {
     "type": "string"
    }
   },
   "X-Sandbox": {
    "description": "`true` on every answer to a sandbox key (`fai-test_`): sample data, never charged.",
    "x-fa": "روی هر پاسخ به کلید آزمایشی (`fai-test_`) `true` است: داده‌ی نمونه، بدون هزینه.",
    "schema": {
     "type": "string"
    }
   },
   "ETag": {
    "description": "Send it back as If-None-Match after the free-repeat window; an unchanged answer is a free 304. Inside the window a repeat is already a free 200 with `X-Replayed: true`.",
    "x-fa": "پس از مدت تکرار رایگان، آن را در If-None-Match برگردانید؛ اگر پاسخ عوض نشده باشد ۳۰۴ رایگان می‌گیرید. در همان مدت، تکرار درخواست خودش یک ۲۰۰ رایگان با `X-Replayed: true` است.",
    "schema": {
     "type": "string"
    }
   }
  },
  "responses": {
   "Error": {
    "description": "Every failure is `{\"detail\": \"<key>\"}` and costs nothing. Validation adds `errors: {field: [code]}`.",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "detail": {
         "type": "string"
        },
        "errors": {
         "type": "object"
        }
       },
       "required": [
        "detail"
       ]
      }
     }
    }
   }
  }
 }
}