Kaleidoscope API Documentation

5-Minute Quickstart

Get up and running with the Kaleidoscope API in under 5 minutes. We'll take you from signup to your first successful API call.

1 Get Your API Key

Sign up at api.kscope.io/signup
Log in to your dashboard
Find your API key in the dashboard

API Access Tiers:

• Free: 300 calls/month
• Starter: 100,000 calls/month
• Business: 300,000 calls/month
• Custom: Unlimited calls + enterprise features

Keep your API key secure: Never commit it to GitHub, use environment variables in production

2 Test Your Authentication

cURL

# Replace YOUR_API_KEY with your actual key
curl 'https://api.kscope.io/auth-test?key=YOUR_API_KEY'

✅ Success Response:

{"status": "success", "message": "Authenticated"}

3 Your First Real API Call - Search SEC Filings

Search for Apple's SEC filings

curl 'https://api.kscope.io/v3/sec/search/AAPL?key=YOUR_API_KEY&content=sec&limit=3'

View example response

{
  "data": [
    {
      "cik": 320193,
      "company_name": "Apple Inc.",
      "date": 1730419200,
      "filer": "Apple Inc.",
      "form": "10-Q",
      "form_desc": "Quarterly report [Sections 13 or 15(d)]",
      "form_group": "Quarterly Reports",
      "acc": "0000320193-24-000123",
      "html": "https://cdn.kscope.io/abc123def456.html",
      "pdf": "https://cdn.kscope.io/abc123def456.pdf",
      "ticker": "AAPL"
    }
  ],
  "total": 2004,
  "status": "success"
}

4 Understanding the Response

Key Fields

ticker - Stock symbol
form - Filing type (10-K, 10-Q, 8-K)
date - Unix timestamp
pdf - Direct link to PDF
html - Direct link to HTML

Response Structure

data - Array of filings
total - Total results available
status - Request status

5 Try Different Searches

Search only 10-K annual reports

curl 'https://api.kscope.io/v3/sec/search/AAPL?key=YOUR_API_KEY&content=sec&form=10-K&limit=5'

Search with keyword

curl 'https://api.kscope.io/v3/sec/search/AAPL?key=YOUR_API_KEY&content=sec&exp=revenue&limit=5'

Search exhibits instead of main filings

curl 'https://api.kscope.io/v3/sec/search/AAPL?key=YOUR_API_KEY&content=exhibits&limit=5'

Quick Reference

Rate Limit: 3,600 requests/hour

Base URL: https://api.kscope.io

Support: support@kscope.io

Dashboard: api.kscope.io/dashboard

🎉 Congratulations! What's Next?

Explore SEC Endpoints Authentication Details Error Handling

Authentication

Use your key for all requests. Get your key now.

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)

                                    import requests 
response = requests.get("https://api.kscope.io/auth-test?key=API-KEY")
print(response.json())
                                

                                    fetch("https://api.kscope.io/auth-test?key=API-KEY")
  .then(response => response.json())
  .then(data => console.log(data));
                                

                                    {
  "status": "success",
  "message": "Authenticated"
}
                                

SEC Filings

Access a comprehensive dataset of SEC filings from the 1990s to present. Filings are processed within seconds of publication by the SEC.

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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 Enterprise	String	Boolean expression
form	String	Restrict results to passed form(s). Use ; between forms to pass more than one form

                                    curl --request GET \
--url 'https://api.kscope.io/v3/sec/search/AAPL?key=API-KEY&content=sec' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v3/sec/search/AAPL?key=API-KEY&content=sec"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v3/sec/search/AAPL?key=API-KEY&content=sec",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "data": [
    {
      "cik": 320193,
      "company_name": "WAGNER SUSAN",
      "date": 1709251200,
      "filer": "WAGNER SUSAN",
      "form": "4",
      "form_desc": "Statement of changes in beneficial ownership of securities",
      "form_group": "Insider Trading",
      "acc": "0000320193-24-000039",
      "html": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.html",
      "ixbrl": "",
      "pdf": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.pdf",
      "ticker": "AAPL",
      "word": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.doc",
      "xbrl": "",
      "xls": ""
    }
  ],
  "total": 2004
, "status": "success"
}
                                

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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 Enterprise	String	Boolean expression
form	String	Restrict results to passed form(s). Use ; between forms to pass more than one form

                                    curl --request GET \
--url 'https://api.kscope.io/v2/sec/search/AAPL?key=API-KEY&content=sec' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/sec/search/AAPL?key=API-KEY&content=sec"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/sec/search/AAPL?key=API-KEY&content=sec",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "data": [
    {
      "CIK": 320193,
      "Company Name": "WAGNER SUSAN",
      "Date": 1709251200,
      "Filer": "WAGNER SUSAN",
      "Form": "4",
      "Form_Desc": "Statement of changes in beneficial ownership of securities",
      "Form_Group": "Insider Trading",
      "acc": "0000320193-24-000039",
      "html": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.html",
      "ixbrl": "",
      "pdf": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.pdf",
      "ticker": "AAPL",
      "word": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.doc",
      "xbrl": "",
      "xls": ""
    }
  ],
  "end": 100,
  "start": 0,
  "total": 2004
}
                                

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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/sec/boolean-expression?key=API-KEY&exp=apple&content=sec&start_date=1609459200&end_date=1735689600' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/sec/boolean-expression?key=API-KEY&exp=apple&content=sec&start_date=1609459200&end_date=1735689600"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/sec/boolean-expression?key=API-KEY&exp=apple&content=sec&start_date=1609459200&end_date=1735689600",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "data": [
    {
      "cik": 320193,
      "company_name": "WAGNER SUSAN",
      "date": 1709251200,
      "filer": "WAGNER SUSAN",
      "form": "4",
      "form_desc": "Statement of changes in beneficial ownership of securities",
      "form_group": "Insider Trading",
      "acc": "0000320193-24-000039",
      "html": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.html",
      "ixbrl": "",
      "pdf": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.pdf",
      "ticker": "AAPL",
      "word": "https://cdn.kscope.io/204d1eb7b1e2b7b369c5bc4086a96c13.doc",
      "xbrl": "",
      "xls": "",
      "blurbs": [
        "Q3 2012 Developed first TJ Maxx Q4 2023 the off-price retailers, it's all the TJX concepts... These operators have the desire to continue to expand across all of their different flags."
      ]
    }
  ],
  "total": 2004,
  "status": "success"
}
                                

Filing Search Realtime

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

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/sec/search/realtime?key=API-KEY&content=sec' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/sec/search/realtime?key=API-KEY&content=sec"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/sec/search/realtime?key=API-KEY&content=sec",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/sec/holdings/037833100?key=API-KEY' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/sec/holdings/TSLA?key=API-KEY"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/sec/holdings/0001172661-23-001741?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    [
  {
    "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/sec/form-d/1452994?key=API-KEY&limit=1' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/sec/form-d/1452994?key=API-KEY&limit=1"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/sec/form-d/1452994?key=API-KEY&limit=1",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/sec/form-c/1744851?key=API-KEY&limit=1' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/sec/form-c/1744851?key=API-KEY&limit=1"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/sec/form-c/1744851?key=API-KEY&limit=1",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v1/sec/form-144/0001234567-23-000123?key=API-KEY&limit=10&offset=20&sort_by=notice_date&sort_order=asc' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v1/sec/form-144/0001234567-23-000123"
payload = {}
headers = {"Content-Type": "application/json"}
params = {
    "key": "API-KEY",
    "limit": 10,
    "offset": 20,
    "sort_by": "notice_date",
    "sort_order": "asc"
}

response = requests.get(url, headers=headers, params=params, data=payload)

print(response.text)
                                

                                    const settings = {
  "url": "https://api.kscope.io/v1/sec/form-144/0001234567-23-000123?key=API-KEY&limit=10&offset=20&sort_by=notice_date&sort_order=asc",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json"
  }
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/insider/320193?key=API-KEY&limit=2' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/insider/TSLA?key=API-KEY&limit=2"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/insider/TSLA?key=API-KEY&limit=2",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/compensation/summary/1214156?key=API-KEY' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/compensation/summary/1214156?key=API-KEY"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/compensation/summary/aapl?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    [
  {
    "acc": "0001193125-22-003583",
    "all_other_compensation": 1386559,
    "bonus": null,
    "cik": 1214156,
    "name": "Tim Cook",
    "optionawards": null,
    "salary": 3000000,
    "stockawards": 82347835,
    "title": "chief executive officer",
    "total": 98734394,
    "year": 2021
  },
  {
    "acc": "0001193125-22-003583",
    "all_other_compensation": 1038259,
    "bonus": null,
    "cik": 1214156,
    "name": "Tim Cook",
    "optionawards": null,
    "salary": 3000000,
    "stockawards": null,
    "title": "chief executive officer",
    "total": 14769259,
    "year": 2020
  },
  {
    "acc": "0001193125-21-001987",
    "all_other_compensation": 1038259,
    "bonus": null,
    "cik": 1214156,
    "name": "Tim Cook",
    "optionawards": null,
    "salary": 3000000,
    "stockawards": null,
    "title": "chief executive officer",
    "total": 14769259,
    "year": 2020
  }
]
                                

Compensation Director

Retrieve compensation data for company directors.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/compensation/directors/1214156?key=API-KEY' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/compensation/directors/1214156?key=API-KEY"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/compensation/directors/aapl?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    [
  {
    "acc": "0001308179-23-000596",
    "all_other_compensation": null,
    "cashpayout": 119946,
    "cik": 1182047,
    "name": "James A. Bell ",
    "optionawards": null,
    "stockawards": 177500,
    "total": 297446,
    "year": 2023
  },
  {
    "acc": "0001308179-23-000019",
    "all_other_compensation": 8773,
    "cashpayout": 100000,
    "cik": 1182047,
    "name": "James Bell",
    "optionawards": null,
    "stockawards": 274941,
    "total": 383714,
    "year": 2023
  },
  {
    "acc": "0001308179-22-000212",
    "all_other_compensation": null,
    "cashpayout": 102500,
    "cik": 1182047,
    "name": "James A. Bell",
    "optionawards": null,
    "stockawards": 152500,
    "total": 255000,
    "year": 2022
  }
]
                                

Corporate Actions

Search corporate actions reported in Form 8-K.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/corporate-actions/818686?key=API-KEY&limit=1' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/corporate-actions/818686?key=API-KEY&limit=1"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/corporate-actions/818686?key=API-KEY&limit=1",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "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
}
                                

Stocks

Get intraday and end-of-day stock data from NASDAQ with 15-minute delay for real-time quotes.

Stock Real-Time Enterprise

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

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

Parameters

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

                                    curl --request GET \
--url 'https://api.kscope.io/v2/stock/real-time?key=API-KEY' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/stock/real-time?key=API-KEY"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/stock/real-time?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "52week_high": "314.67",
  "52week_low": "101.81",
  "change": "3.67",
  "change_per": "1.55",
  "close": "233.19",
  "day_high": "238.98",
  "day_low": "229.29",
  "last_price": "236.86",
  "last_update": "2023-08-23T16:00:00-04:00",
  "open": "229.34",
  "ticker": "TSLA",
  "volume": "95,207,253"
}
                                

Stock Historical Enterprise

Retrieve historical stock prices and performance indicators.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/stock-historical?key=API-KEY' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/stock-historical?key=API-KEY"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/stock-historical?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    [
  {
    "adj_close": 4.778,
    "close": 23.89,
    "div_amt": 0,
    "high": 25,
    "low": 17.54,
    "open": 19,
    "split_coeff": 1,
    "ticker": "TSLA",
    "ts": 1277769600000,
    "volume": 18766300
  },
  {
    "adj_close": 4.766,
    "close": 23.83,
    "div_amt": 0,
    "high": 30.4192,
    "low": 23.3,
    "open": 25.79,
    "split_coeff": 1,
    "ticker": "TSLA",
    "ts": 1277856000000,
    "volume": 17187100
  },
  {
    "adj_close": 4.392,
    "close": 21.96,
    "div_amt": 0,
    "high": 25.92,
    "low": 20.27,
    "open": 25,
    "split_coeff": 1,
    "ticker": "TSLA",
    "ts": 1277942400000,
    "volume": 8218800
  }
]
                                

Stock Delayed Enterprise

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

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/stock-delayed?key=API-KEY' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/stock-delayed?key=API-KEY"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/stock-delayed?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    [
  {
    "adj_close": 4.778,
    "close": 23.89,
    "div_amt": 0,
    "high": 25,
    "low": 17.54,
    "open": 19,
    "split_coeff": 1,
    "ticker": "TSLA",
    "ts": 1277769600000,
    "volume": 18766300
  },
  {
    "adj_close": 4.766,
    "close": 23.83,
    "div_amt": 0,
    "high": 30.4192,
    "low": 23.3,
    "open": 25.79,
    "split_coeff": 1,
    "ticker": "TSLA",
    "ts": 1277856000000,
    "volume": 17187100
  },
  {
    "adj_close": 4.392,
    "close": 21.96,
    "div_amt": 0,
    "high": 25.92,
    "low": 20.27,
    "open": 25,
    "split_coeff": 1,
    "ticker": "TSLA",
    "ts": 1277942400000,
    "volume": 8218800
  }
]
                                

Wealth

Access detailed information about insider activities, including search, gifts, bios, sales, compensation, and holdings.

Search Enterprise

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

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/IF/search?key=API-KEY&university=University%20Of%20Alabama&name_title=officer' \
--header 'Content-Type: application/json'
                                

                                    import requests
response = requests.get("https://api.kscope.io/v2/IF/search?key=API-KEY&university=University%20Of%20Alabama&name_title=officer", headers={"Content-Type": "application/json"})
print(response.json())
                                

                                    fetch("https://api.kscope.io/v2/IF/search?key=API-KEY&university=University%20Of%20Alabama&name_title=officer", {
  headers: {"Content-Type": "application/json"}
})
  .then(response => response.json())
  .then(data => console.log(data));
                                

                                    {
  "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

Inputs

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

                                    curl --request GET \
--url 'https://api.kscope.io/v2/IF/gifts?key=API-KEY&cik=1214156' \
--header 'Content-Type: application/json'
                                

                                    import requests
response = requests.get("https://api.kscope.io/v2/IF/gifts?key=API-KEY&cik=1214156", headers={"Content-Type": "application/json"})
print(response.json())
                                

                                    fetch("https://api.kscope.io/v2/IF/gifts?key=API-KEY&cik=1214156", {
  headers: {"Content-Type": "application/json"}
})
  .then(response => response.json())
  .then(data => console.log(data));
                                

                                    {
  "gifts": [
    {
      "calculated": {
        "stock_price": 192.35,
        "value": 13464500
      },
      "company": {
        "cik": 320193,
        "name": "Apple INC",
        "sic": 3571,
        "sym": "AAPL"
      },
      "notes": [
        "These shares are held through Mr. Cook's trust.",
        "The number of securities reported reflects the acquisition on January 29, 2021 of 230 shares of Apple Inc.'s common stock pursuant to the Apple Inc. Amended Employee Stock Purchase Plan (\"ESPP\") for the ESPP purchase period of August 1, 2020 through January 31, 2021."
      ],
      "price": 0,
      "shares": 70000,
      "ticker": "AAPL",
      "transactionDate": "2021-08-20"
    }
    // Additional gifts truncated for brevity
  ]
}
                                

Bios Enterprise

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

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

Inputs

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

                                    curl --request GET \
--url 'https://api.kscope.io/v2/IF/bio?key=API-KEY&cik=1214156' \
--header 'Content-Type: application/json'
                                

                                    import requests
response = requests.get("https://api.kscope.io/v2/IF/bio?key=API-KEY&cik=1214156", headers={"Content-Type": "application/json"})
print(response.json())
                                

                                    fetch("https://api.kscope.io/v2/IF/bio?key=API-KEY&cik=1214156", {
  headers: {"Content-Type": "application/json"}
})
  .then(response => response.json())
  .then(data => console.log(data));
                                

                                    {
  "bios": [
    {
      "bios": [
        {
          "acc": "0001308179-24-000010",
          "date": 1704931200,
          "desc": "*Key Skills and Qualifications* Tim Cook brings to the Board extensive executive leadership experience in the technology industry including the management of worldwide operations sales service and support. *Career Highlights* Mr. Cook 63 has served as Apple's Chief Executive Officer since 2011 having previously served as Apple's Chief Operating Officer from October 2005.",
          "education": null,
          "picture": null
        }
        // Additional bios truncated for brevity
      ],
      "cik": 1214156,
      "name": "Cook Timothy D"
    }
  ]
}
                                

Sales Enterprise

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

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

Inputs

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

                                    curl --request GET \
--url 'https://api.kscope.io/v2/IF/sales?key=API-KEY&cik=1214156' \
--header 'Content-Type: application/json'
                                

                                    import requests
response = requests.get("https://api.kscope.io/v2/IF/sales?key=API-KEY&cik=1214156", headers={"Content-Type": "application/json"})
print(response.json())
                                

                                    fetch("https://api.kscope.io/v2/IF/sales?key=API-KEY&cik=1214156", {
  headers: {"Content-Type": "application/json"}
})
  .then(response => response.json())
  .then(data => console.log(data));
                                

                                    {
  "sales": [
    {
      "acc": "0000320193-24-000049",
      "directOrIndirectOwnership": {
        "notes": ["These shares are held through Mr. Cook's trust."],
        "value": "D"
      },
      "formtype": "4",
      "issuer": {
        "cik": 320193,
        "name": "Apple Inc.",
        "sic": 3571,
        "sym": "AAPL"
      },
      "period": "2024-04-01",
      "pps": {"value": 169.3},
      "published": 1712187103,
      "securityTitle": {"value": "Common Stock"},
      "sharesOwnedFollowingTransaction": {"value": 3280180},
      "transactionCode": "S",
      "transactionDate": {"value": "2024-04-02"},
      "transactionShares": {"value": 165},
      "txnValue": {"value": 27934.5}
    }
    // Additional sales truncated for brevity
  ]
}
                                

Compensation Enterprise

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

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

Inputs

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

                                    curl --request GET \
--url 'https://api.kscope.io/v2/IF/compensation?key=API-KEY&cik=1214156' \
--header 'Content-Type: application/json'
                                

                                    import requests
response = requests.get("https://api.kscope.io/v2/IF/compensation?key=API-KEY&cik=1214156", headers={"Content-Type": "application/json"})
print(response.json())
                                

                                    fetch("https://api.kscope.io/v2/IF/compensation?key=API-KEY&cik=1214156", {
  headers: {"Content-Type": "application/json"}
})
  .then(response => response.json())
  .then(data => console.log(data));
                                

                                    {
  "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

Inputs

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

                                    curl --request GET \
--url 'https://api.kscope.io/v2/IF/holdings?key=API-KEY&cik=1214156' \
--header 'Content-Type: application/json'
                                

                                    import requests
response = requests.get("https://api.kscope.io/v2/IF/holdings?key=API-KEY&cik=1214156", headers={"Content-Type": "application/json"})
print(response.json())
                                

                                    fetch("https://api.kscope.io/v2/IF/holdings?key=API-KEY&cik=1214156", {
  headers: {"Content-Type": "application/json"}
})
  .then(response => response.json())
  .then(data => console.log(data));
                                

                                    {
  "holdings": [
    {
      "AAPL": {
        "Direct": {
          "sharesOwned": 3280180,
          "transactionDate": "2024-04-02",
          "value": 630942623
        },
        "Indirect": {
          "sharesOwned": null,
          "transactionDate": null,
          "value": null
        },
        "company": {
          "cik": 320193,
          "name": "Apple INC",
          "sic": 3571,
          "sym": "AAPL"
        },
        "stock": {
          "date": 1716249600000,
          "value": 192.35
        }
      }
      // Additional holdings truncated for brevity
    }
  ]
}
                                

SEDAR

Access Canadian securities filings via the SEDAR system since 1997.

SEDAR

Retrieve individual SEDAR filings for Canadian companies.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/sedar/00029882?key=API-KEY&limit=1' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/sedar/00029882?key=API-KEY&limit=1"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/sedar/00029882?key=API-KEY&limit=1",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "data": [
    {
      "accepted": 1692713166,
      "date_filed": 20230822,
      "docid": "06012763-00000001-00029882-ASC_Form_13-501F1_for_Allkem_Limited_-_22_Aug_2023-PDF",
      "document_kdesc": null,
      "document_ktype": "002-002-100035-102584",
      "document_subtype": "102584",
      "document_type": "100035",
      "entities": {
        "fund_group": null,
        "issuer": {
          "cusip": "Q0226L",
          "issuerno": "00029882",
          "name_e": "ALLKEM LIMITED",
          "name_f": "ALLKEM LIMITED",
          "symbol": [
            "AKE:CA"
          ]
        }
      },
      "filing_desc": "Continuous disclosure",
      "html": "https://api.kscope.io/downloadSedar?docid=64e4c0ce8ae0d41da5258192",
      "language": "EN",
      "pages": "0",
      "pdf": "https://api.kscope.io/downloadSedar?docid=64e4c0ce8ae0d41da5258192&format=pdf"
    }
  ],
  "end": 1,
  "start": 0,
  "total": 854
}
                                

Press Releases

Access press releases for companies using ticker symbols.

Press Releases

Fetch the latest press releases by ticker symbol.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

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 --request GET \
--url 'https://api.kscope.io/v2/news/press-releases/AAPL?key=API-KEY&limit=10' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/news/press-releases/AAPL?key=API-KEY&limit=10"

payload={}
headers = {}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

                                    const settings = {
  "url": "https://api.kscope.io/v2/news/press-releases/AAPL?key=API-KEY&limit=10",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
}).fail(function (error) {
  console.error(error);
});
                                

                                    {
  "data": [
    {
      "html": "",
      "meta": {
        "author": "PRNewswire",
        "channels": [
          "Opinion",
          "Press Releases"
        ],
        "id": 37746928,
        "image": "",
        "published": 1710510300,
        "stocks": [
          "AAPL",
          "AMD",
          "BBW",
          "M",
          "WW"
        ],
        "tags": [
          {
            "name": "Banking/Financial Services"
          }
        ],
        "teaser": "NEW YORK March 15 2024 PRNewswire...",
        "title": "Thinking about trading options or...",
        "updated": "Fri, 15 Mar 2024 09:45:05 -0400"
      }
    }
  ],
  "end": 1,
  "groups": {
    "year": [
      2016,
      2017,
      2018,
      2019,
      2020,
      2021,
      2022,
      2023,
      2024
    ]
  },
  "start": 0,
  "total": 970
}
                                

Realtime Transcripts Enterprise

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

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

Parameters

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

                                    curl --request GET \
--url 'https://api.kscope.io/v2/transcripts/realtime?key=API-KEY' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/transcripts/realtime?key=API-KEY"

headers = {
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)

print(response.text)

                                    const settings = {
 "url": "https://api.kscope.io/v2/transcripts/realtime?key=API-KEY",
 "method": "GET",
 "timeout": 0,
 "headers": {
 "Content-Type": "application/json"
 }
};

$.ajax(settings).done(function (response) {
 console.log(response);
}).fail(function (error) {
 console.error(error);
});
                                

                                    {
  "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.

Rate Limit

Limit: 3,600 requests/hour

Reset: Rolling hourly window

Returns 429 status with reset_in field showing seconds until limit resets

Parameters

Parameter	Type	Description
key	String	API key for authentication (Required)
ticker	String	Restrict results to a specific ticker symbol (e.g., TSLA)
date	String	Filter by a specific date (e.g., 2025-03-03)
start_date	String	Start of date range (e.g., 2025-01-01)
end_date	String	End of date range (e.g., 2025-06-30)
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 --request GET \
--url 'https://api.kscope.io/v2/transcripts/historical?key=API-KEY&limit=1' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/transcripts/historical?key=API-KEY&limit=1"

headers = {
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)

print(response.text)

                                    const settings = {
 "url": "https://api.kscope.io/v2/transcripts/historical?key=API-KEY&limit=1",
 "method": "GET",
 "timeout": 0,
 "headers": {
 "Content-Type": "application/json"
 }
};

$.ajax(settings).done(function (response) {
 console.log(response);
}).fail(function (error) {
 console.error(error);
});
                                

                                    {
  "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 Limits

Understand API rate limiting and how to optimize your usage. Monitor your limits through response headers.

Rate Limiting Overview Dev

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)

                                    {
  "error": {
    "message": "You have exceeded the rate limit for this endpoint, please wait for reset: 2145 seconds",
    "requests_used": 3601,
    "limit": 3600,
    "type": "RATELIMIT",
    "reset_in": 2145,
    "cooldown": 2145
  }
}
                                

                                    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;
    }
}
                                

                                    #!/bin/bash

# Make API call and check for rate limiting
response=$(curl -s -w "\n%{http_code}" "https://api.kscope.io/v2/sec/search/AAPL?key=API-KEY")
http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" = "429" ]; then
    # Extract reset_in from JSON response
    reset_in=$(echo "$body" | grep -o '"reset_in":[0-9]*' | cut -d: -f2)
    echo "❌ Rate limited. Wait $reset_in seconds until top of hour"
    
    # Parse full error for details
    echo "$body" | python -m json.tool
else
    echo "✅ Success"
    echo "$body" | python -m json.tool
fi
                                

Error Codes

Understand API error codes and their meanings. All errors return a consistent JSON structure with code, type, and message fields.

API Error Codes Dev

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

                                    {
  "error": {
    "code": 400,
    "type": "INPUT",
    "message": "Invalid ticker symbol format"
  }
}
                                

                                    {
  "error": {
    "code": 401,
    "type": "AUTH",
    "message": "Invalid API key provided"
  }
}
                                

                                    {
  "error": {
    "message": "You have exceeded the rate limit for this endpoint, please wait for reset: 1823 seconds",
    "requests_used": 3601,
    "limit": 3600,
    "type": "RATELIMIT",
    "reset_in": 1823,
    "cooldown": 1823
  }
}
                                

                                    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
                                

                                    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
                                