واجهة SEC Filings API

اعرض البيانات الوصفية لإيداعات SEC حسب الشركة، بما في ذلك 10-K و10-Q و8-K وForm 4 و13F-HR.

نقطة النهاية والطلب

متاح باستخدام مفتاح Narwhal API.

نقطة نهاية REST

GET /v1/companies/{company_id}/filings

طلب

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/cmp_a1b2c3d4e5f678901234567890abcdef/filings?forms=10-K,10-Q&filed_from=2020-01-01&filed_to=2027-01-01&limit=50" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

يستخدم MCP companies_list_filings مع المعلمات المقابلة أدناه. يعيد REST وMCP مخطط الاستجابة نفسه ويشتركان في حساب الحصة.

المعلمات

الاسم	مطلوب	النوع	المعنى
`company_id`	نعم	المسار · معرّف Narwhal غير قابل للتفسير	هوية الشركة الثابتة التي يعيدها البحث. ويظل رمز التداول وCIK اسمين بديلين، لا هوية دائمة للمسار.
`forms`	لا	الاستعلام · comma-separated SEC النماذج	رموز النماذج الدقيقة الحساسة لحالة الأحرف. يطابق النموذج الأساسي أيضًا تعديله /A ما لم تُستبعد التعديلات.
`filed_from`	لا	الاستعلام · YYYY-MM-DD	حد أدنى شامل لتاريخ الإيداع.
`filed_to`	لا	الاستعلام · YYYY-MM-DD	حد أعلى حصري لتاريخ الإيداع. يجب أن يكون لاحقًا لـ filed_from.
`include_amendments`	لا	الاستعلام · منطقي	أدرج التعديلات عند طلب نموذج أساسي. القيمة الافتراضية صحيحة.
`limit`	لا	الاستعلام · عدد صحيح, 1–100	الحد الأقصى للإيداعات المعادة. الافتراضي 50.
`cursor`	لا	الاستعلام · سلسلة نصية غير قابلة للتفسير	رمز المتابعة من الصفحة السابقة. وهو مرتبط بالاستعلام والمرشحات الأصلية.

مرشحات نماذج SEC

استخدم رموز استمارات SEC الدقيقة. يمكن أن تتضمن الاستمارة الأساسية مشتقاتها /A التعديل، مثل 10-K/A أو 4/A، ما لم تُستبعد التعديلات.

النماذج	المعنى
`10-K`	تقرير الشركة السنوي
`10-Q`	تقرير شركة فصلي
`8-K`	أحداث الشركة الجوهرية
`20-F / 6-K`	تقارير المُصدر الخاص الأجنبي
`DEF 14A`	تصويتات الوكالة ومجالس الإدارة وتعويضات التنفيذيين
`Forms 3 / 4 / 5`	الملكية النافعة للمطلعين وتغييراتها
`Schedule 13D / 13G`	المالكون النافعون الكبار
`13F-HR`	حيازات المدير المؤسسي
`S-1 / S-3 / 424B`	التسجيلات والعروض ونشرات الإصدار

تشرح هذه القائمة الأشكال الشائعة. وليست قائمة سماح ثابتة.

الاستجابة

{
  "company": {
    "id": "cmp_a1b2c3d4e5f678901234567890abcdef",
    "name": "Apple Inc.",
    "cik": "0000320193"
  },
  "filings": [
    {
      "accession_number": "0000320193-24-000123",
      "form": "10-K",
      "filed_on": "2024-11-01",
      "accepted_at": "2024-11-01T10:01:36Z",
      "report_period": "2024-09-28",
      "is_amendment": false,
      "items": [],
      "filing_index_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/0000320193-24-000123-index.html",
      "primary_document_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm"
    }
  ],
  "next_cursor": null,
  "as_of": "2026-08-29T12:00:00Z"
}

حقل	النوع	مطلوب	المعنى
`company`	كائن	نعم	معرّف الشركة واسمها وCIK الثابتة للجهة المُصدرة المطلوبة.
`filings`	مصفوفة	نعم	البيانات الوصفية للإيداعات مرتبة حسب وقت القبول ورقم Accession، من الأحدث أولًا.
`next_cursor`	سلسلة نصية أو قيمة فارغة	نعم	رمز متابعة غير شفاف مرتبط بالمرشح، أو قيمة فارغة عند الاكتمال.
`as_of`	طابع وقت UTC	نعم	وقت اللقطة المشترك بين كل إيداع في الصفحة.

الأخطاء والحصة

400 invalid_query — الاستعلام أو التاريخ أو الاستمارة أو الحد أو المؤشر غير صالح.
401 invalid_api_key — مفتاح Bearer مفقود أو مرفوض.
404 company_not_found — معرّف الشركة غير معروف في الإصدار المقبول.
429 rate_limit_exceeded أو quota_exhausted — استُنفدت الحصة القصيرة أو الشهرية المشتركة.
503 companies_unavailable — Companies معطّلة، أو الحقوق غير نشطة، أو لا يمكن تقديم إصدار كامل مقبول.

لا تستهلك إخفاقات المصادقة والطلبات المرفوضة بسبب التقييد الحصة الشهرية. وتستخدم استدعاءات REST وMCP الناجحة مخصص الحساب نفسه.

نطاق الإصدار الأول

يعيد الإصدار الأول البيانات الوصفية وروابط وثائق SEC الأساسية فقط. ولا يتضمن أجسام الإيداعات أو المرفقات أو حقائق XBRL أو معاملات المطلعين أو البيانات المالية أو حيازات 13F.

تقتصر التغطية على مجموعة المُصدرين المقبولة. اقرأ وقت as_of في الاستجابة وصفحة التغطية لمعرفة اللقطة المتاحة.