Kaleidoscope API Documentation

Authentication

All requests require an API key. API keys never expire automatically - they remain valid until manually deleted in your dashboard.

Inputs

Parameter	Type	Description
API-KEY	String	Generated through the developer portal (Required)

cURL

Python

JavaScript

JSON

Filing Search

Search over 18M SEC filings with keywords, Boolean expressions, and 20+ filters. All filing types supported. Data available from the 1990s to present.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to ticker, CIK (Required)
content	String	Content to search against. Available values: sec, exhibits, agreements (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)
offset	Int	Used as a way to page through data
start_date	Int	Start from a date with a timestamp (Unix Timestamp)
end_date	Int	End at a date with a timestamp (Unix Timestamp)
exp	String	Boolean expression	enterprise
form	String	Restrict results to passed form(s). Use ; between forms to pass more than one form

cURL

Python

JavaScript

JSON

Filing Search

Search over 18M SEC filings with keywords, Boolean expressions, and 20+ filters. All filing types supported. Data available from the 1990s to present.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to ticker, CIK (Required)
content	String	Content to search against. Available values: sec, exhibits, agreements (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)
start	Int	Used as a way to page through data. If end is 100 then the next start be 100
sd	Int	Start from a date with a timestamp (Unix Timestamp)
ed	Int	End at a date with a timestamp (Unix Timestamp)
exp	String	Boolean expression	enterprise
form	String	Restrict results to passed form(s). Use ; between forms to pass more than one form

cURL

Python

JavaScript

JSON

Filing Search with Boolean Expression Enterprise

Enterprise feature: Search over 18M SEC filings using advanced boolean expressions. Supports all filing types from the 1990s to present.

Parameters

Parameter	Type	Description
key	String	API key for authentication (Required)
exp	String	Boolean expression for search (Required)
content	String	Content to search against. Available values: sec, exhibits, agreements. Defaults to sec
limit	Int	Maximum number of results to return (default: 100, max: 100)
offset	Int	Number of results to skip for pagination (e.g., 100 to skip first 100 results)
start_date	Int	Start date for search as Unix timestamp. Defaults to 4 years ago
end_date	Int	End date for search as Unix timestamp. Defaults to current date

cURL

Python

JavaScript

JSON

Filing Search Realtime

Get all SEC filings for the current UTC day. Returns the latest filings across all companies.

Parameters

Parameter	Type	Description
key	String	API key for authentication (Required)
content	String	Content to search against. Available values: sec, exhibits, agreements. Defaults to sec
limit	Int	Maximum number of results to return (default: 100, max: 100)
start	Int	Number of results to skip for pagination (e.g., 100 to skip first 100 results)

cURL

Python

JavaScript

JSON

{
  "data": [
    {
      "cik": 320193,
      "company_name": "Apple Inc.",
      "date": 1735689600,
      "filer": "Apple Inc.",
      "form": "8-K",
      "form_desc": "Current report",
      "form_group": "Other",
      "acc": "0000320193-25-000001",
      "html": "https://cdn.kscope.io/abc123.html",
      "ixbrl": "",
      "pdf": "https://cdn.kscope.io/abc123.pdf",
      "ticker": "AAPL",
      "word": "https://cdn.kscope.io/abc123.doc",
      "xbrl": "",
      "xls": ""
    },
    {
      "cik": 789019,
      "company_name": "Microsoft Corp",
      "date": 1735689600,
      "filer": "Microsoft Corp",
      "form": "4",
      "form_desc": "Statement of changes in beneficial ownership",
      "form_group": "Insider Trading",
      "acc": "0000789019-25-000012",
      "html": "https://cdn.kscope.io/def456.html",
      "ixbrl": "",
      "pdf": "https://cdn.kscope.io/def456.pdf",
      "ticker": "MSFT",
      "word": "https://cdn.kscope.io/def456.doc",
      "xbrl": "",
      "xls": ""
    }
  ],
  "total": 542,
  "start": 0,
  "end": 2
}

Holdings

Retrieve equity holdings from Form 13F filings for institutional managers with $100M+ in assets.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to cusip, ticker, CIK (Required)
type	String	Format: HTML, PDF, Word, XLS, XBRL, XBRL-HTML (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)

cURL

Python

JavaScript

JSON

[
  {
    "acc": "0001600035-23-000004",
    "cusip": "037833100",
    "diff_value": 7402583,
    "diff_votingAuthority_Total": -11217,
    "hccn": "STONEBRIDGE CAPITAL ADVISORS LLC",
    "hcik": 1600035,
    "id": "0001600035-23-000004|921",
    "ides": "SOLE",
    "issuer": "APPLE INC COM",
    "per": 1688083200,
    "per_sshp": -3.4043315163949353,
    "per_value": 13.624392743559541,
    "per_votingAuthority_Total": -3.4043315163949353,
    "prev_value": 54333306,
    "prev_votingAuthority_Total": 329492,
    "pt": 941287911,
    "sshp": 318275,
    "sspt": "SH",
    "stamp": 1692748800,
    "toc": "Stock",
    "val": 61735889,
    "vnone": 0,
    "vshare": 0,
    "vsole": 318275,
    "vtotal": 318275
  },
  {
    "acc": "0001990195-23-000011",
    "cusip": "037833100",
    "diff_value": 1418783,
    "diff_votingAuthority_Total": -8751,
    "hccn": "RAPPAPORT REICHES CAPITAL MANAGEMENT, LLC",
    "hcik": 1990195,
    "id": "0001990195-23-000011|75",
    "ides": "SOLE",
    "issuer": "Apple Inc",
    "per": 1688083200,
    "per_sshp": -8.164141225647532,
    "per_value": 8.028020094961276,
    "per_votingAuthority_Total": -8.165074270359035,
    "prev_value": 17672888,
    "prev_votingAuthority_Total": 107176,
    "pt": 239507250,
    "sshp": 98426,
    "sspt": "SH",
    "stamp": 1692748800,
    "toc": "Stock",
    "val": 19091671,
    "vnone": 0,
    "vshare": 0,
    "vsole": 98425,
    "vtotal": 98425
  }
]

Form D - Private Securities Offerings

Access exempt registrations for small companies and funds pre-IPO.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to acc, CIK (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)

cURL

Python

JavaScript

JSON

{
  "count": 1,
  "items": [
    {
      "acc": "0000919574-13-005814",
      "cik": "0001452994",
      "issuerList": [],
      "offeringData": {
        "businessCombinationTransaction": {
          "clarificationOfResponse": null,
          "isBusinessCombinationTransaction": "false"
        },
        "durationOfOffering": {
          "moreThanOneYear": "true"
        },
        "federalExemptionsExclusions": [
          "06b",
          "3C",
          "3C.1"
        ],
        "industryGroup": {
          "industryGroupType": "Pooled Investment Fund",
          "investmentFundInfo": {
            "investmentFundType": "Hedge Fund",
            "is40Act": "false"
          }
        },
        "investors": {
          "hasNonAccreditedInvestors": "false",
          "totalNumberAlreadyInvested": "82"
        },
        "issuerSize": {
          "aggregateNetAssetValueRange": "Decline to Disclose"
        },
        "minimumInvestmentAccepted": null,
        "offeringSalesAmounts": {
          "clarificationOfResponse": null,
          "totalAmountSold": "168811146",
          "totalOfferingAmount": "Indefinite",
          "totalRemaining": "Indefinite"
        },
        "salesCommissionsFindersFees": {
          "clarificationOfResponse": null,
          "findersFees": {
            "dollarAmount": "0",
            "isEstimate": "true"
          },
          "salesCommissions": {
            "dollarAmount": "0",
            "isEstimate": "true"
          }
        },
        "salesCompensationList": [],
        "signatureBlock": [
          {
            "issuerName": "HORSEMAN EUROPEAN SELECT FUND, L.P.",
            "nameOfSigner": "Kevin Blanchfield",
            "signatureDate": "2013-10-10",
            "signatureName": "/s/Kevin Blanchfield",
            "signatureTitle": "Director of the General Partner of the Issuer"
          },
          {
            "issuerName": "HORSEMAN EUROPEAN SELECT FUND, L.P.",
            "nameOfSigner": "Kevin Blanchfield",
            "signatureDate": "2013-10-10",
            "signatureName": "/s/Kevin Blanchfield",
            "signatureTitle": "Director of the General Partner of the Issuer"
          }
        ],
        "typeOfFiling": {
          "dateOfFirstSale": {
            "dateOfFirstSale": "2008-01-01"
          },
          "newOrAmendment": {
            "isAmendment": "true",
            "previousAccessionNumber": "0000919574-12-005654"
          }
        },
        "typesOfSecuritiesOffered": {
          "isPooledInvestmentFundType": "true"
        },
        "useOfProceeds": {
          "clarificationOfResponse": null,
          "grossProceedsUsed": {
            "dollarAmount": "0",
            "isEstimate": "true"
          }
        }
      },
      "primaryIssuer": {
        "ccc": null,
        "cik": "0001452994",
        "edgarPreviousNameList": {
          "previousName": "HORSEMAN EUROPEAN SELECT FUND LP"
        },
        "entityName": "HORSEMAN EUROPEAN SELECT FUND, L.P.",
        "entityType": "Limited Partnership",
        "entityTypeOtherDesc": null,
        "issuerAddress": {
          "city": "LONDON",
          "stateOrCountry": "X0",
          "stateOrCountryDescription": "UNITED KINGDOM",
          "street1": "Horseman Capital International Limited",
          "street2": "9 CHESTER CLOSE",
          "zipCode": "SW1X 7BE"
        },
        "issuerPhoneNumber": "44 (0)20 7838 7580",
        "issuerPreviousNameList": null,
        "jurisdictionOfInc": "DELAWARE",
        "yearOfInc": {
          "overFiveYears": "true"
        }
      },
      "relatedPersonsList": [
        {
          "relatedPersonAddress": {
            "city": "London",
            "stateOrCountry": "X0",
            "stateOrCountryDescription": "UNITED KINGDOM",
            "street1": "c/o Horseman Capital Management, L.P.",
            "street2": "9 Chester Close",
            "zipCode": "SW1X 7BE"
          },
          "relatedPersonName": {
            "firstName": "John",
            "lastName": "Horseman"
          },
          "relatedPersonRelationshipList": [
            "Director"
          ]
        },
        {
          "relatedPersonAddress": {
            "city": "New York",
            "stateOrCountry": "NY",
            "stateOrCountryDescription": "NEW YORK",
            "street1": "c/o Meteora Partners, LLC",
            "street2": "11 Broadway, Suite 965",
            "zipCode": "10004"
          },
          "relatedPersonName": {
            "firstName": "Kevin",
            "lastName": "Blanchfield"
          },
          "relatedPersonRelationshipList": [
            "Director"
          ]
        },
        {
          "relatedPersonAddress": {
            "city": "New York",
            "stateOrCountry": "NY",
            "stateOrCountryDescription": "NEW YORK",
            "street1": "19 East 88 Street",
            "zipCode": "10128"
          },
          "relatedPersonName": {
            "firstName": "Marsha",
            "lastName": "Roth"
          },
          "relatedPersonRelationshipList": [
            "Director"
          ]
        },
        {
          "relatedPersonAddress": {
            "city": "Athens",
            "stateOrCountry": "J3",
            "stateOrCountryDescription": "GREECE",
            "street1": "KO 4A Voula",
            "zipCode": "16673"
          },
          "relatedPersonName": {
            "firstName": "Paschalis",
            "lastName": "Economidis"
          },
          "relatedPersonRelationshipList": [
            "Director"
          ]
        }
      ]
    }
  ]
}

Form C - Crowdfunding

Retrieve crowdfunding offering statements filed via Form C.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to acc, CIK (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)

cURL

Python

JavaScript

JSON

{
  "count": 1,
  "items": [
    {
      "acc": "0001665160-19-000404",
      "annualReportDisclosureRequirements": {
        "actReceivedMostRecentFiscalYear": "16802.00",
        "actReceivedPriorFiscalYear": "0.00",
        "cashEquiMostRecentFiscalYear": "21269.00",
        "cashEquiPriorFiscalYear": "0.00",
        "costGoodsSoldMostRecentFiscalYear": "0.00",
        "costGoodsSoldPriorFiscalYear": "0.00",
        "currentEmployees": "1",
        "issueJurisdictionSecuritiesOffering": [
          "AL",
          "AK",
          "AZ",
          "AR",
          "CA",
          "CO",
          "CT",
          "DC",
          "DE",
          "FL",
          "GA",
          "HI",
          "ID",
          "IL",
          "IN",
          "IA",
          "KS",
          "KY",
          "LA",
          "ME",
          "MD",
          "MA",
          "MI",
          "MN",
          "MS",
          "MO",
          "MT",
          "NE",
          "NV",
          "NH",
          "NJ",
          "NM",
          "NY",
          "NC",
          "ND",
          "OH",
          "OK",
          "OR",
          "PA",
          "PR",
          "RI",
          "SC",
          "SD",
          "TN",
          "TX",
          "UT",
          "VT",
          "VA",
          "WA",
          "WV",
          "WI",
          "WY"
        ],
        "longTermDebtMostRecentFiscalYear": "0.00",
        "longTermDebtPriorFiscalYear": "0.00",
        "netIncomeMostRecentFiscalYear": "-147186.00",
        "netIncomePriorFiscalYear": "0.00",
        "revenueMostRecentFiscalYear": "0.00",
        "revenuePriorFiscalYear": "0.00",
        "shortTermDebtMostRecentFiscalYear": "0.00",
        "shortTermDebtPriorFiscalYear": "0.00",
        "taxPaidMostRecentFiscalYear": "0.00",
        "taxPaidPriorFiscalYear": "0.00",
        "totalAssetMostRecentFiscalYear": "38071.00",
        "totalAssetPriorFiscalYear": "0.00"
      },
      "cik": "0001744851",
      "issuerInformation": {
        "commissionCik": "0001665160",
        "commissionFileNumber": "007-00007",
        "companyName": "StartEngine Capital, LLC",
        "isAmendment": "true",
        "issuerInfo": {
          "issuerAddress": {
            "city": "Sagle",
            "stateOrCountry": "ID",
            "street1": "273 Birch Banks",
            "zipCode": "83860"
          },
          "issuerWebsite": "www.rhino-hide.com",
          "legalStatus": {
            "dateIncorporation": "06-13-2018",
            "jurisdictionOrganization": "ID",
            "legalStatusForm": "Limited Liability Company",
            "legalStatusOtherDesc": null
          },
          "nameOfIssuer": "Rhino Hide LLC"
        },
        "natureOfAmendment": "Issuer has updated its offering with full year 2018 financials and extended the end date of the offering."
      },
      "offeringInformation": {
        "compensationAmount": "6 percent",
        "deadlineDate": "06-24-2019",
        "descOverSubscription": [
          "At issuer's discretion"
        ],
        "financialInterest": "N/A",
        "maximumOfferingAmount": "1070000.00",
        "noOfSecurityOffered": "10000",
        "offeringAmount": "10000.00",
        "overSubscriptionAccepted": "Y",
        "overSubscriptionAllocationType": "Other",
        "price": "1.00000",
        "priceDeterminationMethod": "N/A",
        "securityOfferedOtherDesc": null,
        "securityOfferedType": "Common Stock"
      },
      "signatureInfo": {
        "issuerSignature": {
          "issuer": "Rhino Hide LLC",
          "issuerSignature": "Jason Giddings",
          "issuerTitle": "CEO, Principal Executive Officer and Manager, Principal Financial Officer and Principal Accounting Officer"
        },
        "signaturePersons": [
          {
            "personSignature": "Jason Giddings",
            "personTitle": "CEO, Principal Executive Officer and Manager, Principal Financial Officer and Principal Accounting Officer",
            "signatureDate": "04-24-2019"
          }
        ]
      }
    }
  ]
}

Form 144 - Restricted Sales

Retrieve Form 144 filings for proposed sales of restricted or control securities by providing an identifier (accession number, timestamp, SEC file number, or issuer CIK) and optional filters.

Parameters

Parameter	Type	Description
identifier	String	Unique identifier: accession number (e.g., '0001234567-23-000123'), timestamp (e.g., '1234567890'), SEC file number (e.g., '001-40244'), or issuer CIK (e.g., '0001840776') (Required)
name_of_person	String	Name of the insider (e.g., 'KAUFFMAN ROBERT I')
notice_date	String	Exact notice date of the filing (format: YYYY-MM-DD, e.g., '2025-04-28')
notice_date_gte	String	Start date for notice date range (format: YYYY-MM-DD, e.g., '2025-04-01')
notice_date_lte	String	End date for notice date range (format: YYYY-MM-DD, e.g., '2025-04-30')
securities_exchange_name	String	Stock exchange (e.g., 'NYSE', 'NASDAQ')
broker_name	String	Broker name (e.g., 'Merrill Lynch')
issuer_city	String	City of the issuer (e.g., 'TRAVERSE CITY')
limit	Int	Number of results to return (1 to 10000, default=50)
offset	Int	Number of results to skip for pagination (default: 0)
sort_by	String	Sort field: 'notice_date' or 'acc_stamp' (default='notice_date')
sort_order	String	Sort order: 'asc' or 'desc' (default='desc')

cURL

Python

JavaScript

JSON

{
  "total": {
    "value": 5,
    "relation": "eq"
  },
  "data": [
    {
      "acc": "0001234567-23-000123",
      "acc_stamp": 1234567890,
      "filer_info": {
        "filer_credentials": {
          "cik": "0001124462",
          "ccc": "XXXXXXXX"
        },
        "live_test_flag": "LIVE",
        "contact": {},
        "flags": {
          "override_internet_flag": false
        },
        "notifications": {
          "notification_email": []
        }
      },
      "form_data": {
        "issuer_info": {
          "issuer_cik": "0001840776",
          "issuer_name": "Hagerty, Inc.",
          "sec_file_number": "001-40244",
          "issuer_address": {
            "city": "TRAVERSE CITY",
            "state_or_country": "MI",
            "zip_code": "49684",
            "street1": "121 DRIVERS EDGE",
            "street2": ""
          },
          "issuer_contact_phone": "800-922-4050",
          "name_of_person_for_whose_account_the_securities_are_to_be_sold": "KAUFFMAN ROBERT I",
          "relationships_to_issuer": {
            "relationship_to_issuer": ["Director"]
          }
        },
        "securities_information": [
          {
            "securities_class_title": "Common",
            "broker_or_market_maker_details": {
              "name": "Merrill Lynch",
              "address": {
                "street1": "200 Park Ave, 13th Fl",
                "street2": "",
                "city": "New York",
                "state_or_country": "NY",
                "zip_code": "10166"
              }
            },
            "no_of_units_sold": 1149,
            "aggregate_market_value": 10364.0,
            "no_of_units_outstanding": 90032391,
            "approx_sale_date": "2025-04-25",
            "securities_exchange_name": "NYSE"
          }
        ],
        "securities_to_be_sold": [],
        "notice_signature": {
          "notice_date": "2025-04-28",
          "plan_adoption_dates": {
            "plan_adoption_date": ["2024-08-09"]
          },
          "signature": "Robert I. Kauffman"
        },
        "documents": [],
        "remarks": "",
        "nothing_to_report_flag_on_securities_sold_in_past_3_months": "N",
        "securities_sold_in_past_3_months": []
      }
    }
  ]
}

Insider Transactions

Fetch insider transaction details for non-derivative and derivative securities.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to ticker, CIK (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)
start	Int	Start results from
sd	String	Start date
ed	String	End date

cURL

Python

JavaScript

JSON

{
  "total": 2,
  "txns": [
    {
      "acc": "0000320193-23-000079",
      "filer": {
        "address": "ONE APPLE PARK WAY  CUPERTINO CA 95014 ",
        "cik": 1767094,
        "name": "O'BRIEN DEIRDRE",
        "title": "Senior Vice President"
      },
      "filing": {
        "date": "2023-08-08",
        "excel": "https://cdn.kscope.io/a77b5bcdcfab4fab85387cc92e149507.xlsx",
        "form": "4",
        "html": "https://cdn.kscope.io/a77b5bcdcfab4fab85387cc92e149507.html",
        "pdf": "https://cdn.kscope.io/a77b5bcdcfab4fab85387cc92e149507.pdf",
        "word": "https://cdn.kscope.io/a77b5bcdcfab4fab85387cc92e149507.doc"
      },
      "issuer": {
        "cik": 320193,
        "name": "Apple Inc."
      },
      "txn": {
        "exercisePrice": 0,
        "isDerivativeTransaction": false,
        "marketValue": 2753216.64,
        "ownershipType": "D",
        "pricePerShare": 178.56,
        "securityTitle": "Common Stock",
        "shares": 15419,
        "sharesOwnedFollowing": 136445,
        "transactionCode": "S",
        "transactionDate": "2023-08-07",
        "transactionId": null
      },
      "type": "Non-Derivative"
    },
    {
      "acc": "0000320193-23-000079",
      "filer": {
        "address": "ONE APPLE PARK WAY  CUPERTINO CA 95014 ",
        "cik": 1767094,
        "name": "O'BRIEN DEIRDRE",
        "title": "Senior Vice President"
      },
      "filing": {
        "date": "2023-08-08",
        "excel": "https://cdn.kscope.io/a77b5bcdcfab4fab85387cc92e149507.xlsx",
        "form": "4",
        "html": "https://cdn.kscope.io/a77b5bcdcfab4fab85387cc92e149507.html",
        "pdf": "https://cdn.kscope.io/a77b5bcdcfab4fab85387cc92e149507.pdf",
        "word": "https://cdn.kscope.io/a77b5bcdcfab4fab85387cc92e149507.doc"
      },
      "issuer": {
        "cik": 320193,
        "name": "Apple Inc."
      },
      "txn": {
        "exercisePrice": 0,
        "isDerivativeTransaction": true,
        "marketValue": 0,
        "ownershipType": "D",
        "pricePerShare": 0,
        "securityTitle": "Restricted Stock Unit",
        "shares": 31896,
        "sharesOwnedFollowing": 0,
        "transactionCode": "M",
        "transactionDate": "2023-08-05",
        "transactionId": null
      },
      "type": "Derivative"
    }
  ]
}

Compensation Summary

Fetch summary compensation data for key executives.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to acc, CIK, ticker (Required)
sort	String	Sort retrieved data by asc or desc
year	Int	Filter retrieved data by specific year

cURL

Python

JavaScript

JSON

Compensation Director

Retrieve compensation data for company directors.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to acc, CIK, ticker (Required)
sort	String	Sort retrieved data by asc or desc
year	Int	Filter retrieved data by specific year

cURL

Python

JavaScript

JSON

Corporate Actions

Search corporate actions reported in Form 8-K.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to ticker, CIK (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)

cURL

Python

JavaScript

JSON

{
  "data": [
    {
      "acc": "0001193125-23-219539",
      "cik": 818686,
      "company name": "TEVA PHARMACEUTICAL INDUSTRIES LTD",
      "date": 1692835200,
      "docid": "0001193125-23-219539",
      "filer": "TEVA PHARMACEUTICAL INDUSTRIES LTD",
      "form": "8-K",
      "form_desc": "Current report pursuant to Section 13 or 15(d)",
      "form_group": "8k",
      "html": "https://cdn.kscope.io/7a5adf3349a66b6ec59479d48fff598c.html",
      "items": [
        "Item 1.01 - Entry into a Material Definitive Agreement",
        "Item 7.01 - Regulation FD Disclosure",
        "Item 9.01 - Financial Statements and Exhibits"
      ],
      "ixbrl": "https://cdn.kscope.io/7a5adf3349a66b6ec59479d48fff598c-ixbrl.html",
      "pdf": "https://cdn.kscope.io/7a5adf3349a66b6ec59479d48fff598c.pdf",
      "ticker": "",
      "word": "https://cdn.kscope.io/7a5adf3349a66b6ec59479d48fff598c.doc",
      "xbrl": "https://cdn.kscope.io/7a5adf3349a66b6ec59479d48fff598c-xbrl.html",
      "xls": "https://cdn.kscope.io/7a5adf3349a66b6ec59479d48fff598c.xlsx"
    }
  ],
  "end": null,
  "start": null,
  "total": null
}

Stock Real-Time Enterprise

Access real-time stock prices with a 15-minute delay. Data from NASDAQ exchange.

Parameters

Parameter	Type	Description
API-KEY	String	API key (Required)

cURL

Python

JavaScript

JSON

Stock Historical Enterprise

Retrieve historical stock prices and performance indicators.

Parameters

Parameter	Type	Description
limit	Int	Maximum number of results to return (default: 100, max: 100)
sd	String	Start date as a timestamp
ed	String	End date as a timestamp

cURL

Python

JavaScript

JSON

Stock Delayed Enterprise

Enterprise feature: Access delayed stock prices and performance indicators. Requires enterprise tier access.

Parameters

Parameter	Type	Description
ticker	String	Restrict results to ticker (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)
start_date	String	Start date as a timestamp
end_date	String	End date as a timestamp

cURL

Python

JavaScript

JSON

Search Enterprise

Search and filter the Wealth dataset by person name, CIK, title, university, city, state, or limit results.

Inputs

Parameter	Type	Description
key	String	API key (Required)
Name	String	Search using a person name. Can be a full or partial name
CIK	Integer	CIK identifier
Name_title	String	Person Title. Searches across all person companies for a match
University	String	Person University. Full or partial names are accepted
City	String	City of residence
State	String	State search
limit	Integer	Maximum number of results to return (default: 100, max: 100)

cURL

Python

JavaScript

JSON

{
  "data": [
    {
      "cik": 1645511,
      "companies": [
        {
          "cik": 889900,
          "company": {
            "ccn": "Patterson-UTI Energy Inc.",
            "cik": 889900,
            "exchange": "NGS",
            "ticker": "PTEN"
          },
          "name": "Patterson UTI Energy INC",
          "sic": 1381,
          "sym": "PTEN"
        }
      ],
      "current_holdings": {
        "D": {
          "acc": "0001209191-24-005682",
          "published": 1716343620,
          "transactionDate": {"value": "2024-05-20"},
          "value": {"value": 2007895}
        }
      },
      "education": ["Marietta College"],
      "hasGifts": true,
      "latest_sale": {
        "acc": "0001209191-24-005682",
        "directOrIndirectOwnership": {"value": "D"},
        "formtype": "4",
        "issuer": {
          "cik": 889900,
          "name": "Patterson UTI Energy INC",
          "sic": 1381,
          "sym": "PTEN"
        },
        "period": "2024-05-20",
        "pps": {"value": 11.55},
        "sharesOwnedFollowingTransaction": {"value": 2007895},
        "transactionCode": "S",
        "transactionDate": {"value": "2024-05-20"},
        "transactionShares": {"value": 150000}
      },
      "name": {
        "city": "HOUSTON",
        "name": "Drummond Robert Wayne Jr",
        "state": "TX",
        "titles": [
          {
            "company": "KEY ENERGY SERVICES INC",
            "company_cik": 318996,
            "title": "President and COO, Officer"
          }
        ],
        "zip": "77010"
      }
    }
    // Additional results truncated for brevity
  ]
}

Gifts Enterprise

Retrieve all gift transactions for a person, identified by CIK.

Inputs

Parameter	Type	Description
key	String	API key (Required)
cik	Integer	CIK identifier (Required)

cURL

Python

JavaScript

JSON

Bios Enterprise

Retrieve all identified bios for a person, identified by CIK.

Inputs

Parameter	Type	Description
key	String	API key (Required)
cik	Integer	CIK identifier (Required)

cURL

Python

JavaScript

JSON

Sales Enterprise

Retrieve all sales transactions for a person, identified by CIK. Typically includes transaction codes [S,D].

Inputs

Parameter	Type	Description
key	String	API key (Required)
cik	Integer	CIK identifier (Required)

cURL

Python

JavaScript

JSON

Compensation Enterprise

Retrieve all compensation data for a person, identified by CIK. Includes summary and/or director compensation.

Inputs

Parameter	Type	Description
key	String	API key (Required)
cik	Integer	CIK identifier (Required)

cURL

Python

JavaScript

JSON

{
  "compensation": [
    {
      "director": null,
      "summary": [
        {
          "acc": "0001308179-24-000010",
          "all_other_compensation": 63209845,
          "cik": 1214156,
          "date": "2024-01-11",
          "issuer": 320193,
          "name": "Tim Cook",
          "non_equity_compensation": 2526112,
          "optionawards": 10713450,
          "salary": 3000000,
          "stockawards": 46970283,
          "title": "Chief Executive Officer",
          "total": 63209845,
          "year": 2023
        }
        // Additional summary entries truncated for brevity
      ]
    },
    {
      "director": [
        {
          "acc": "0000320187-22-000041",
          "all_other_compensation": 20000,
          "cashpayout": 150000,
          "ccn": "COOK TIMOTHY D",
          "cik": 1214156,
          "date": "2022-07-21",
          "issuer": 320187,
          "name": "Timothy D. Cook",
          "stockawards": 179453,
          "total": 349453,
          "year": 2022
        }
        // Additional director entries truncated for brevity
      ],
      "summary": null
    }
  ]
}

Holdings Enterprise

Retrieve all holdings (common shares) data for a person, identified by CIK.

Inputs

Parameter	Type	Description
key	String	API key (Required)
cik	Integer	CIK identifier (Required)

cURL

Python

JavaScript

JSON

SEDAR

Retrieve individual SEDAR filings for Canadian companies.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to cusip, ticker, CIK (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)
page	Int	Returns a page of data
symbol	String	DEC:CA

cURL

Python

JavaScript

JSON

Press Releases

Fetch the latest press releases by ticker symbol.

Parameters

Parameter	Type	Description
identifier	String	Restrict results to a ticker (Required)
limit	Int	Maximum number of results to return (default: 100, max: 100)
start	Int	Used as a way to page through data. If end is 100 then the next start be 100
year	Int	Filter retrieved data by specific year
sort	String	Sort retrieved data by asc or desc
sd	Int	Start from a date with a timestamp (Unix Timestamp)
ed	Int	End at a date with a timestamp (Unix Timestamp)

cURL

Python

JavaScript

JSON

Realtime Transcripts Enterprise

Fetch the latest transcripts for the current day in Eastern Standard Time (EST, UTC-5).

Parameters

Parameter	Type	Description
key	String	API key for authentication (Required)

cURL

Python

JavaScript

JSON

{
  "status": "success",
  "total": 1,
  "data": [
    {
      "call_id": "686c36bf8933e80001524354",
      "call_title": "Rockland Trust Q2 2025 Earnings Call",
      "created_at": "2025-07-24T18:59:03.491034Z",
      "description": "Rockland Trust discusses Q2 2025 financial performance, focusing on loan growth and acquisitions.",
      "duration": 54,
      "end_time": "2025-07-24T19:56:43Z",
      "exchange": "NASDAQ",
      "headline": "Rockland Trust reports Q2 net income of $51.1 million with strong CNI loan growth.",
      "language": "en",
      "name": "Independent Bank",
      "participants": [
        {
          "call_id": "686c36bf8933e80001524354",
          "human_verified": false,
          "mentions": 2,
          "name": "Operator",
          "organization": "Rockland Trust",
          "participant_id": "818a6d5f-445d-418f-bfbf-df9f4e66e2a3",
          "role": "Moderator"
        }
      ],
      "securities": null,
      "start_time": "2025-07-24T18:59:03Z",
      "status": "COMPLETED",
      "summary": {
        "call_id": "686c36bf8933e80001524354",
        "created_at": "2025-07-24T18:59:03.491034Z",
        "language": "en",
        "summary": "Rockland Trust reported a strong Q2 with $51.1 million net income, driven by CNI loan growth and improved net interest margin.",
        "summary_id": "470c7faa-6a7c-4c44-a09b-3e88a4ac2e20",
        "symbol": "INDB",
        "transcript_id": "686c36bf8933e80001524354",
        "updated_at": "2025-07-24T19:56:53.407012Z"
      },
      "symbol": "INDB",
      "ticker": "INDB",
      "transcripts": [
        {
          "language": "en",
          "segments": [
            {
              "end_time": "2025-07-24T18:59:10Z",
              "segment_id": 1,
              "speaker": "Operator",
              "start_time": "2025-07-24T18:59:03Z",
              "text": "Welcome to the Rockland Trust Q2 2025 earnings call."
            }
          ],
          "text": "Welcome to the Rockland Trust Q2 2025 earnings call...",
          "transcript_id": "686c36bf8933e80001524354",
          "type": "full"
        }
      ],
      "updated_at": "2025-07-24T19:56:53.407012Z",
      "audio": {
        "content_type": "audio/mpeg",
        "quality": "192kbps",
        "url": "https://cdn.kscope.io/ks-trsc-6880e17947721300018799cd.mp3"
      }
    }
  ]
}

Historical Transcripts Enterprise

Fetch historical transcripts with optional filters for ticker, date, date range, call title, and status. Use 'limit' and 'offset' for pagination to navigate through large result sets.

Parameters

Parameter	Type	Description
key	String	API key for authentication (Required)
ticker	String	Restrict results to a specific ticker symbol (e.g., TSLA)
start_date	Integer	Start of date range as Unix timestamp (e.g., 1704067200 for Jan 1, 2024)
end_date	Integer	End of date range as Unix timestamp (e.g., 1719792000 for Jun 30, 2024)
call_title	String	Keywords to search in call title (case-insensitive, e.g., Q4)
status	String	Filter by transcript status (e.g., COMPLETED)
limit	Int	Maximum number of results to return (default: 100, max: 100)
offset	Int	Number of results to skip for pagination (default: 0)

cURL

Python

JavaScript

JSON

{
  "status": "success",
  "total": 1,
  "offset": 0,
  "data": [
    {
      "call_id": "6683a4c32e2683b6e9b7c88",
      "call_title": "Tesla Q4 2025 Earnings Call",
      "created_at": "2025-03-03T10:38:40Z",
      "description": "Tesla discusses record Q4 production and plans for autonomy and Optimus in 2025.",
      "duration": 73,
      "end_time": "2025-03-03T11:51:40Z",
      "exchange": "TSX",
      "figis": [
        "BBG012313HQ9",
        "BBG0113GCNR4",
        "BBG001SQKGD7"
      ],
      "headline": "Tesla delivers record production in Q4 and outlines ambitious plans for autonomy and Optimus.",
      "language": "en",
      "name": "TESLA INC - CDR",
      "participants": [
        {
          "call_id": "6683a4c32e2683b6e9b7c88",
          "human_verified": false,
          "mentions": 2,
          "name": "Operator",
          "organization": "Tesla Inc",
          "participant_id": "818a6d5f-445d-418f-bfbf-df9f4e66e2a3",
          "role": "Moderator"
        }
      ],
      "securities": [
        {
          "figi": "BBG012313HQ9",
          "figi_composite": "BBG012313HQ9",
          "figi_share_class": "BBG001SQKGD7",
          "isin": "US88160R1014",
          "mic_code": "XTSX",
          "name": "Tesla Inc",
          "refinitiv_exch_code": "TSX",
          "symbol": "TSLA"
        }
      ],
      "start_time": "2025-03-03T10:38:40Z",
      "status": "COMPLETED",
      "summary": {
        "call_id": "6683a4c32e2683b6e9b7c88",
        "created_at": "2025-03-03T10:38:40Z",
        "language": "en",
        "summary": "Tesla reported record Q4 production and outlined plans for autonomy and Optimus.",
        "summary_id": "470c7faa-6a7c-4c44-a09b-3e88a4ac2e20",
        "symbol": "TSLA",
        "transcript_id": "6683a4c32e2683b6e9b7c88",
        "updated_at": "2025-03-03T11:51:40Z"
      },
      "symbol": "TSLA",
      "ticker": "TSLA",
      "transcripts": [
        {
          "language": "en",
          "segments": [
            {
              "end_time": "2025-03-03T10:38:47Z",
              "segment_id": 1,
              "speaker": "Operator",
              "start_time": "2025-03-03T10:38:40Z",
              "text": "Welcome to the Tesla Q4 2025 earnings call."
            }
          ],
          "text": "Welcome to the Tesla Q4 2025 earnings call...",
          "transcript_id": "6683a4c32e2683b6e9b7c88",
          "type": "full"
        }
      ],
      "updated_at": "2025-03-03T11:51:40Z",
      "audio": {
        "content_type": "audio/mpeg",
        "quality": "192kbps",
        "url": "https://cdn.kscope.io/ks-trsc-6683a4c32e2683b6e9b7c88.mp3"
      }
    }
  ]
}

Rate Limiting Overview

All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are applied per API key on an hourly rolling window.

Rate Limiting Details

Aspect	Value	Description
Default Limit	3,600/hour	Standard rate limit for all API endpoints
Time Window	1 hour	Rolling window that resets every hour on the hour
Reset Time	Top of hour	Limits reset at :00 of each hour (e.g., 1:00, 2:00, 3:00)
Error Code	429	HTTP status returned when rate limit exceeded
Retry After	Variable	Seconds until the next hour boundary (provided in error response)

429 Response

Python

JavaScript

cURL

import requests
import time

def make_api_call_with_rate_handling(url, params):
    response = requests.get(url, params=params)
    
    # Handle rate limit exceeded
    if response.status_code == 429:
        error_data = response.json().get('error', {})
        reset_in = error_data.get('reset_in', 3600)
        requests_used = error_data.get('requests_used', 0)
        limit = error_data.get('limit', 3600)
        
        print(f"❌ Rate limit exceeded: {requests_used}/{limit} requests used")
        print(f"⏰ Resets in {reset_in} seconds (at top of hour)")
        
        # Wait and retry (optional)
        if reset_in < 300:  # If less than 5 minutes, wait
            print(f"Waiting {reset_in} seconds...")
            time.sleep(reset_in)
            return make_api_call_with_rate_handling(url, params)
        else:
            raise Exception(f"Rate limited. Try again in {reset_in} seconds")
    
    return response

# Keep track of your requests locally
class RateLimitTracker:
    def __init__(self):
        self.requests_this_hour = 0
        self.hour_started = time.time()
    
    def check_before_request(self):
        # Reset counter if new hour
        current_time = time.time()
        if current_time - self.hour_started >= 3600:
            self.requests_this_hour = 0
            self.hour_started = current_time
        
        # Check if approaching limit
        if self.requests_this_hour >= 3500:
            print(f"⚠️ Warning: Approaching rate limit ({self.requests_this_hour}/3600)")
        
        self.requests_this_hour += 1
        return self.requests_this_hour < 3600

async function apiCallWithRateHandling(url) {
    const response = await fetch(url);
    
    // Handle rate limit exceeded
    if (response.status === 429) {
        const errorData = await response.json();
        const error = errorData.error || {};
        const resetIn = error.reset_in || 3600;
        const requestsUsed = error.requests_used || 0;
        const limit = error.limit || 3600;
        
        console.error(`❌ Rate limit exceeded: ${requestsUsed}/${limit} requests used`);
        console.log(`⏰ Resets in ${resetIn} seconds (at top of hour)`);
        
        // Wait and retry (optional)
        if (resetIn < 300) {  // If less than 5 minutes, wait
            console.log(`Waiting ${resetIn} seconds...`);
            await new Promise(resolve => setTimeout(resolve, resetIn * 1000));
            return apiCallWithRateHandling(url);
        } else {
            throw new Error(`Rate limited. Try again in ${resetIn} seconds`);
        }
    }
    
    return response;
}

// Keep track of your requests locally
class RateLimitTracker {
    constructor() {
        this.requestsThisHour = 0;
        this.hourStarted = Date.now();
    }
    
    checkBeforeRequest() {
        // Reset counter if new hour
        const currentTime = Date.now();
        if (currentTime - this.hourStarted >= 3600000) {
            this.requestsThisHour = 0;
            this.hourStarted = currentTime;
        }
        
        // Check if approaching limit
        if (this.requestsThisHour >= 3500) {
            console.warn(`⚠️ Warning: Approaching rate limit (${this.requestsThisHour}/3600)`);
        }
        
        this.requestsThisHour++;
        return this.requestsThisHour < 3600;
    }
}

API Error Codes

The API returns standardized error responses to help you handle issues programmatically. Every error includes detailed information to help you identify and resolve the issue quickly.

Error Code Reference

HTTP Code	Error Type	Common Causes & Solutions
400	`INPUT`	Bad Request • Missing required parameters • Invalid date format (use Unix timestamp) • Invalid ticker symbol • Malformed JSON body Solution: Check parameter names and formats
401	`AUTH`	Unauthorized • Missing API key parameter • Invalid or expired API key • Key suspended or revoked Solution: Verify your API key at api.kscope.io/dashboard
403	`PERMISSION`	Forbidden • Endpoint requires premium/enterprise tier • Missing specific permissions • IP restrictions in place Solution: Upgrade your plan or contact support
404	`DATA`	Not Found • Invalid endpoint URL • Resource doesn't exist (e.g., invalid CIK) • Data not available for date range Solution: Verify endpoint path and identifiers
429	`RATELIMIT`	Too Many Requests • Exceeded hourly rate limit • Too many concurrent requests • Burst limit exceeded Solution: Implement rate limiting and retry logic
500	`SERVER_ERROR`	Internal Server Error • Unexpected server error • Database connection issue • Unhandled exception Solution: Retry after a few seconds. If persists, contact support

400 Bad Request

401 Unauthorized

429 Rate Limited

Python

JavaScript

cURL

import requests
import time
import logging

class APIClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.kscope.io"
        self.logger = logging.getLogger(__name__)
    
    def make_request(self, endpoint, params=None, retries=3):
        """Make API request with comprehensive error handling"""
        url = f"{self.base_url}{endpoint}"
        if params is None:
            params = {}
        params['key'] = self.api_key
        
        for attempt in range(retries):
            try:
                response = requests.get(url, params=params, timeout=30)
                
                # Check rate limit headers
                remaining = response.headers.get('X-RateLimit-Remaining')
                if remaining and int(remaining) < 100:
                    self.logger.warning(f"Low rate limit: {remaining} requests remaining")
                
                # Handle successful response
                if response.status_code == 200:
                    return response.json()
                
                # Handle errors
                error_data = response.json().get('error', {})
                error_type = error_data.get('type')
                error_message = error_data.get('message', 'Unknown error')
                
                # Error-specific handling
                if response.status_code == 400:
                    # Bad request - don't retry, fix the request
                    self.logger.error(f"Bad request: {error_message}")
                    raise ValueError(f"Invalid parameters: {error_message}")
                    
                elif response.status_code == 401:
                    # Authentication error - don't retry
                    self.logger.error("Authentication failed")
                    raise PermissionError("Invalid or missing API key")
                    
                elif response.status_code == 403:
                    # Permission denied - don't retry
                    self.logger.error(f"Permission denied: {error_message}")
                    raise PermissionError(f"Insufficient permissions: {error_message}")
                    
                elif response.status_code == 404:
                    # Not found - don't retry
                    self.logger.warning(f"Resource not found: {error_message}")
                    return None
                    
                elif response.status_code == 429:
                    # Rate limited - wait and retry
                    reset_in = error_data.get('reset_in', 60)
                    self.logger.warning(f"Rate limited. Waiting {reset_in} seconds...")
                    time.sleep(min(reset_in, 300))  # Cap at 5 minutes
                    continue
                    
                elif response.status_code >= 500:
                    # Server error - retry with backoff
                    wait_time = 2 ** attempt  # Exponential backoff
                    self.logger.warning(f"Server error. Retrying in {wait_time}s...")
                    time.sleep(wait_time)
                    continue
                    
                else:
                    # Unknown error
                    self.logger.error(f"Unexpected error {response.status_code}: {error_message}")
                    raise Exception(f"API error {response.status_code}: {error_message}")
                    
            except requests.exceptions.Timeout:
                self.logger.warning(f"Request timeout. Attempt {attempt + 1}/{retries}")
                if attempt == retries - 1:
                    raise
                time.sleep(2 ** attempt)
                
            except requests.exceptions.ConnectionError as e:
                self.logger.warning(f"Connection error: {e}. Attempt {attempt + 1}/{retries}")
                if attempt == retries - 1:
                    raise
                time.sleep(2 ** attempt)
        
        raise Exception(f"Failed after {retries} attempts")

# Usage example
client = APIClient("YOUR_API_KEY")
try:
    data = client.make_request("/v2/sec/search/AAPL", {"content": "sec"})
    if data:
        print(f"Found {len(data)} results")
except ValueError as e:
    print(f"Fix your request: {e}")
except PermissionError as e:
    print(f"Authentication issue: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

class APIClient {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://api.kscope.io';
    }
    
    async makeRequest(endpoint, params = {}, retries = 3) {
        const url = new URL(this.baseUrl + endpoint);
        params.key = this.apiKey;
        Object.keys(params).forEach(key => 
            url.searchParams.append(key, params[key])
        );
        
        for (let attempt = 0; attempt < retries; attempt++) {
            try {
                const response = await fetch(url.toString(), {
                    timeout: 30000
                });
                
                // Check rate limit headers
                const remaining = response.headers.get('X-RateLimit-Remaining');
                if (remaining && parseInt(remaining) < 100) {
                    console.warn(`⚠️ Low rate limit: ${remaining} requests remaining`);
                }
                
                // Handle successful response
                if (response.status === 200) {
                    return await response.json();
                }
                
                // Parse error response
                const errorData = await response.json();
                const error = errorData.error || {};
                const errorType = error.type;
                const errorMessage = error.message || 'Unknown error';
                
                // Error-specific handling
                switch (response.status) {
                    case 400:
                        // Bad request - don't retry
                        console.error(`❌ Bad request: ${errorMessage}`);
                        throw new Error(`Invalid parameters: ${errorMessage}`);
                        
                    case 401:
                        // Authentication error - don't retry
                        console.error('❌ Authentication failed');
                        throw new Error('Invalid or missing API key');
                        
                    case 403:
                        // Permission denied - don't retry
                        console.error(`❌ Permission denied: ${errorMessage}`);
                        throw new Error(`Insufficient permissions: ${errorMessage}`);
                        
                    case 404:
                        // Not found - don't retry
                        console.warn(`⚠️ Resource not found: ${errorMessage}`);
                        return null;
                        
                    case 429:
                        // Rate limited - wait and retry
                        const resetIn = error.reset_in || 60;
                        console.warn(`⏳ Rate limited. Waiting ${resetIn} seconds...`);
                        await new Promise(resolve => 
                            setTimeout(resolve, Math.min(resetIn * 1000, 300000))
                        );
                        continue;
                        
                    case 502:
                    case 503:
                    case 504:
                        // Server errors - retry with backoff
                        const waitTime = Math.pow(2, attempt);
                        console.warn(`🔄 Server error. Retrying in ${waitTime}s...`);
                        await new Promise(resolve => 
                            setTimeout(resolve, waitTime * 1000)
                        );
                        continue;
                        
                    default:
                        // Unknown error
                        console.error(`❌ Unexpected error ${response.status}: ${errorMessage}`);
                        throw new Error(`API error ${response.status}: ${errorMessage}`);
                }
                
            } catch (error) {
                if (error.name === 'AbortError') {
                    console.warn(`⏱️ Request timeout. Attempt ${attempt + 1}/${retries}`);
                    if (attempt === retries - 1) throw error;
                    await new Promise(resolve => 
                        setTimeout(resolve, Math.pow(2, attempt) * 1000)
                    );
                } else if (attempt === retries - 1) {
                    throw error;
                }
            }
        }
        
        throw new Error(`Failed after ${retries} attempts`);
    }
}

// Usage example
const client = new APIClient('YOUR_API_KEY');

// With async/await
async function fetchData() {
    try {
        const data = await client.makeRequest('/v2/sec/search/AAPL', {
            content: 'sec'
        });
        if (data) {
            console.log(`✅ Found ${data.length} results`);
        }
    } catch (error) {
        if (error.message.includes('Invalid parameters')) {
            console.error('Fix your request:', error.message);
        } else if (error.message.includes('Invalid or missing API key')) {
            console.error('Check your API key');
        } else {
            console.error('Unexpected error:', error.message);
        }
    }
}

fetchData();

#!/bin/bash

# Function to make API request with error handling
make_api_request() {
    local endpoint="$1"
    local api_key="$2"
    local max_retries=3
    local retry_count=0
    
    while [ $retry_count -lt $max_retries ]; do
        # Make request and capture response with headers
        response=$(curl -s -w "\n%{http_code}" -H "Accept: application/json" \
            "https://api.kscope.io${endpoint}?key=${api_key}")
        
        # Extract HTTP status code
        http_code=$(echo "$response" | tail -n1)
        body=$(echo "$response" | sed '$d')
        
        case $http_code in
            200)
                # Success
                echo "✅ Success:"
                echo "$body" | jq '.'
                return 0
                ;;
            400)
                # Bad request - don't retry
                echo "❌ Bad Request (400):" >&2
                echo "$body" | jq -r '.error.message' >&2
                return 1
                ;;
            401)
                # Unauthorized - don't retry
                echo "❌ Unauthorized (401): Check your API key" >&2
                return 1
                ;;
            403)
                # Forbidden - don't retry
                echo "❌ Forbidden (403): Insufficient permissions" >&2
                echo "$body" | jq -r '.error.message' >&2
                return 1
                ;;
            404)
                # Not found - don't retry
                echo "⚠️ Not Found (404): Resource doesn't exist" >&2
                return 1
                ;;
            429)
                # Rate limited - wait and retry
                reset_in=$(echo "$body" | jq -r '.error.reset_in // 60')
                echo "⏳ Rate Limited (429). Waiting ${reset_in} seconds..." >&2
                sleep "$reset_in"
                ((retry_count++))
                continue
                ;;
            5*)
                # Server error - retry with exponential backoff
                wait_time=$((2 ** retry_count))
                echo "🔄 Server Error ($http_code). Retrying in ${wait_time}s..." >&2
                sleep "$wait_time"
                ((retry_count++))
                continue
                ;;
            *)
                # Unknown error
                echo "❌ Unknown Error ($http_code)" >&2
                echo "$body" >&2
                return 1
                ;;
        esac
    done
    
    echo "❌ Failed after $max_retries attempts" >&2
    return 1
}

# Usage example
API_KEY="YOUR_API_KEY"
ENDPOINT="/v2/sec/search/AAPL"

if make_api_request "$ENDPOINT" "$API_KEY"; then
    echo "Request successful"
else
    echo "Request failed"
    exit 1
fi

Exponential Backoff

import time
import random
import requests
from typing import Optional, Dict, Any

def exponential_backoff_retry(
    url: str,
    params: Dict[str, Any],
    max_retries: int = 5,
    base_delay: float = 1.0,
    max_delay: float = 60.0,
    jitter: bool = True
) -> Optional[Dict]:
    """
    Retry with exponential backoff and optional jitter.
    
    Args:
        url: API endpoint URL
        params: Request parameters
        max_retries: Maximum number of retry attempts
        base_delay: Initial delay in seconds
        max_delay: Maximum delay between retries
        jitter: Add random jitter to prevent thundering herd
    """
    
    for attempt in range(max_retries):
        try:
            response = requests.get(url, params=params, timeout=30)
            
            if response.status_code == 200:
                return response.json()
            
            # Don't retry client errors (4xx) except rate limiting
            if 400 <= response.status_code < 500 and response.status_code != 429:
                print(f"Client error {response.status_code}: Not retrying")
                return None
            
            # Calculate delay with exponential backoff
            delay = min(base_delay * (2 ** attempt), max_delay)
            
            # Add jitter to prevent thundering herd
            if jitter:
                delay = delay * (0.5 + random.random())
            
            print(f"Attempt {attempt + 1} failed. Retrying in {delay:.2f} seconds...")
            time.sleep(delay)
            
        except requests.exceptions.RequestException as e:
            print(f"Request error: {e}")
            if attempt == max_retries - 1:
                raise
            
            # Use same backoff strategy for network errors
            delay = min(base_delay * (2 ** attempt), max_delay)
            if jitter:
                delay = delay * (0.5 + random.random())
            time.sleep(delay)
    
    return None

# Circuit breaker pattern
class CircuitBreaker:
    def __init__(self, failure_threshold=5, recovery_timeout=60):
        self.failure_threshold = failure_threshold
        self.recovery_timeout = recovery_timeout
        self.failure_count = 0
        self.last_failure_time = None
        self.state = 'closed'  # closed, open, half-open
    
    def call(self, func, *args, **kwargs):
        if self.state == 'open':
            if time.time() - self.last_failure_time > self.recovery_timeout:
                self.state = 'half-open'
                print("Circuit breaker: Trying half-open state")
            else:
                raise Exception("Circuit breaker is OPEN")
        
        try:
            result = func(*args, **kwargs)
            if self.state == 'half-open':
                self.state = 'closed'
                self.failure_count = 0
                print("Circuit breaker: Recovered, now CLOSED")
            return result
        except Exception as e:
            self.failure_count += 1
            self.last_failure_time = time.time()
            
            if self.failure_count >= self.failure_threshold:
                self.state = 'open'
                print(f"Circuit breaker: OPEN after {self.failure_count} failures")
            
            raise e

5-Minute Quickstart

Authentication

Authentication

Inputs

SEC Filings

Filing Search

Parameters

Filing Search

Parameters

Filing Search with Boolean Expression Enterprise

Parameters

Filing Search Realtime

Parameters

Holdings

Parameters

Form D - Private Securities Offerings

Parameters

Form C - Crowdfunding

Parameters

Form 144 - Restricted Sales

Parameters

Insider Transactions

Parameters

Compensation Summary

Parameters

Compensation Director

Parameters

Corporate Actions

Parameters

Stocks

Stock Real-Time Enterprise

Parameters

Stock Historical Enterprise

Parameters

Stock Delayed Enterprise

Parameters

Wealth

Search Enterprise

Inputs

Gifts Enterprise

Inputs

Bios Enterprise

Inputs

Sales Enterprise

Inputs

Compensation Enterprise

Inputs

Holdings Enterprise

Inputs

SEDAR

SEDAR

Parameters

Press Releases

Press Releases

Parameters

Realtime Transcripts Enterprise

Parameters

Historical Transcripts Enterprise

Parameters

Rate Limits

Rate Limiting Overview

Rate Limiting Details

Error Codes

API Error Codes

Error Code Reference