Kaleidoscope API Documentation

REST API reference for SEC filings, SEDAR, stocks, M&A, press releases, transcripts and insider data. Code samples in cURL, Python and JavaScript.

5-Minute Quickstart

Get up and running with the Kaleidoscope API in under 5 minutes. From your API key to your first successful call.

1 endpoint

Make your first API call

Get up and running in two steps: (1) append ?key=YOUR-API-KEY to any endpoint URL, (2) run the example...

Get up and running in two steps: (1) append ?key=YOUR-API-KEY to any endpoint URL, (2) run the example below.

The first request hits /auth-test — a lightweight endpoint that just verifies your key. No permissions or paid plan required. Once that returns success, you can call any of the endpoints documented below.

Authentication: all requests use a query-string API key (?key=...). Keys never expire automatically — they remain valid until you delete them from your dashboard. Treat them like passwords: don't commit them to public repos.

Authentication parameter

Parameter	Type	Description
key	String	Your API key from the developer portal (Required on every request)

Step 1 — Verify your key

cURL

Python

JavaScript

                                    curl 'https://api.kscope.io/auth-test?key=API-KEY'
                                

                                    import requests

response = requests.get(
    'https://api.kscope.io/auth-test',
    params={'key': 'API-KEY'}
)
print(response.json())
# => {'status': 'success', 'message': 'Authenticated'}
                                

                                    const params = new URLSearchParams({ key: 'API-KEY' });
fetch(`https://api.kscope.io/auth-test?${params}`)
  .then(r => r.json())
  .then(data => console.log(data));
// => { status: 'success', message: 'Authenticated' }
                                

Step 2 — Fetch real data

cURL

Python

JavaScript

                                    # Look up the most recent SEC filings for Apple
curl 'https://api.kscope.io/v3/sec/search/AAPL?key=API-KEY&limit=5'
                                

                                    import requests

response = requests.get(
    'https://api.kscope.io/v3/sec/search/AAPL',
    params={'key': 'API-KEY', 'limit': 5}
)
filings = response.json()['data']
for f in filings:
    print(f['form'], f['filing_date'], f.get('title'))
                                

                                    const params = new URLSearchParams({ key: 'API-KEY', limit: 5 });
fetch(`https://api.kscope.io/v3/sec/search/AAPL?${params}`)
  .then(r => r.json())
  .then(({ data }) => {
    data.forEach(f => console.log(f.form, f.filing_date, f.title));
  });
                                

Successful response

JSON

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

Failure response (invalid or missing key)

JSON

                                    {
  "error": {
    "code": 401,
    "type": "AUTH_FAILED",
    "message": "Invalid or missing API key",
    "hint": "Append ?key=YOUR-API-KEY to the request"
  }
}
                                

Rate limit: 3,600 requests/hour

Rolling hourly window · Exceeding the limit returns HTTP 429 with a reset_in field indicating seconds until reset

SEC Filings

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

14 endpoints

Filing Search

Search over 18M SEC filings with keywords, Boolean expressions, and 20+ filters. All filing types...

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Filing Search with Boolean Expression enterprise

Enterprise feature: Search over 18M SEC filings using advanced boolean expressions. Supports all filing...

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

Parameters

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

Example Request

cURL

Python

JavaScript

                                    curl --request GET \
--url 'https://api.kscope.io/v2/sec/search/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/search/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/search/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);
});
                                

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Filing Search Realtime

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

SEC Filings List enterprise

List all SEC filings for a company by ticker or CIK, newest first. Returns one entry per filing with its...

List all SEC filings for a company by ticker or CIK, newest first. Returns one entry per filing with its accession number, form type, and filing date. Filter by form type(s) and date range. Any SEC form type can be requested (10-K, 8-K, 4, SC 13D, S-1, ...); the 10-K, 10-Q, 8-K, 20-F and 40-F families automatically include their /A amendment variants.

Parameters

Parameter	Type	Description
identifier	String	Ticker symbol or CIK number (Required)
form	String	Form type(s), comma-separated (e.g. '10-K,10-Q'). Known families include /A variants automatically
start_date	Int	Start from a date with a timestamp (Unix Timestamp)
end_date	Int	End at a date with a timestamp (Unix Timestamp)
limit	Int	Maximum number of results to return (default: 25, max: 100)
offset	Int	Used as a way to page through data

Example Request

cURL

Python

JavaScript

                                    curl --request GET \
--url 'https://api.kscope.io/v4/sec/filings/AAPL?key=API-KEY&form=10-K,10-Q' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v4/sec/filings/AAPL?key=API-KEY&form=10-K,10-Q"

payload={}
headers = {}

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

print(response.text)
                                

                                    const settings = {
  "url": "https://api.kscope.io/v4/sec/filings/AAPL?key=API-KEY&form=10-K,10-Q",
  "method": "GET",
  "timeout": 0,
};

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

Example Response

JSON

                                    {
  "status": "success",
  "data": [
    {
      "accession_number": "0000320193-25-000079",
      "cik": 320193,
      "company_name": "Apple Inc.",
      "form_type": "10-K",
      "filing_date": "2025-10-31",
      "filing_date_formatted": "Oct 31, 2025",
      "links": {
        "html": "https://cdn.kscope.io/4d5be67bc105cf4df08769c616be0d6a.html",
        "pdf": "https://cdn.kscope.io/4d5be67bc105cf4df08769c616be0d6a.pdf",
        "word": "https://cdn.kscope.io/4d5be67bc105cf4df08769c616be0d6a.doc",
        "xls": "https://cdn.kscope.io/4d5be67bc105cf4df08769c616be0d6a.xlsx"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 839,
      "limit": 25,
      "offset": 0,
      "has_more": true
    }
  }
}
                                

Filing Items enterprise

List the items/sections of a single SEC filing by accession number — e.g. every item of a 10-K (Item 1...

List the items/sections of a single SEC filing by accession number — e.g. every item of a 10-K (Item 1 Business, Item 1A Risk Factors, ...). Only the 10-K, 10-Q, 8-K, 20-F and 40-F form families (and their /A variants) are sectioned into items. Each item's section object includes a 'text' URL — GET it to retrieve the full content of that section (plain text by default; add &format=html for the original markup).

Parameters

Parameter	Type	Description
accession	String	SEC accession number, e.g. 0000320193-26-000013 (Required)

Example Request

cURL

Python

JavaScript

                                    curl --request GET \
--url 'https://api.kscope.io/v4/sec/filings/0000320193-26-000013/items?key=API-KEY' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v4/sec/filings/0000320193-26-000013/items?key=API-KEY"

payload={}
headers = {}

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

print(response.text)
                                

                                    const settings = {
  "url": "https://api.kscope.io/v4/sec/filings/0000320193-26-000013/items?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

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

Example Response

JSON

                                    {
  "status": "success",
  "data": {
    "accession_number": "0000320193-26-000013",
    "cik": 320193,
    "form_type": "10-Q",
    "filing_date": "2026-05-01",
    "filing_date_formatted": "May 01, 2026",
    "items": [
      {
        "docid": "0000320193-26-000013-1-1",
        "kitem": "1-1",
        "section": {
          "code": "10-Q/P1-1",
          "text": "https://api.kscope.io/v4/sec/items/0000320193-26-000013-1-1/content?key=API-KEY",
          "kitem": "1-1",
          "label": "Part 1 Item 1 - Financial Statements"
        }
      }
    ],
    "links": {
      "html": "https://cdn.kscope.io/58e9a71c5abba33bf1ec8ae7dcc5950e.html",
      "pdf": "https://cdn.kscope.io/58e9a71c5abba33bf1ec8ae7dcc5950e.pdf",
      "word": "https://cdn.kscope.io/58e9a71c5abba33bf1ec8ae7dcc5950e.doc",
      "xls": "https://cdn.kscope.io/58e9a71c5abba33bf1ec8ae7dcc5950e.xlsx"
    }
  },
  "meta": {}
}
                                

Company Items enterprise

List all filing items/sections for a company by ticker or CIK, newest first — every sectioned item across...

List all filing items/sections for a company by ticker or CIK, newest first — every sectioned item across the company's 10-K, 10-Q, 8-K, 20-F and 40-F filings (and /A variants). Filter by form type(s) and date range. Use the Filing Items endpoint to expand a single filing instead. Each item's section object includes a 'text' URL — GET it to retrieve the full content of that section (plain text by default; add &format=html for the original markup).

Parameters

Parameter	Type	Description
identifier	String	Ticker symbol or CIK number (Required)
form	String	Form type(s), comma-separated. Supported: 10-K, 10-Q, 8-K, 20-F, 40-F (and /A variants)
start_date	Int	Start from a date with a timestamp (Unix Timestamp)
end_date	Int	End at a date with a timestamp (Unix Timestamp)
limit	Int	Maximum number of results to return (default: 25, max: 100)
offset	Int	Used as a way to page through data

Example Request

cURL

Python

JavaScript

                                    curl --request GET \
--url 'https://api.kscope.io/v4/sec/items/AAPL?key=API-KEY&form=8-K' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v4/sec/items/AAPL?key=API-KEY&form=8-K"

payload={}
headers = {}

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

print(response.text)
                                

                                    const settings = {
  "url": "https://api.kscope.io/v4/sec/items/AAPL?key=API-KEY&form=8-K",
  "method": "GET",
  "timeout": 0,
};

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

Example Response

JSON

                                    {
  "status": "success",
  "data": [
    {
      "docid": "0000320193-25-000079-1-1a",
      "accession_number": "0000320193-25-000079",
      "cik": 320193,
      "form_type": "10-K",
      "filing_date": "2025-10-31",
      "filing_date_formatted": "Oct 31, 2025",
      "kitem": "1-1a",
      "section": {
        "code": "10-K/1A",
        "text": "https://api.kscope.io/v4/sec/items/0000320193-25-000079-1-1a/content?key=API-KEY",
        "kitem": "1-1a",
        "label": "Item 1A - Risk Factors"
      },
      "links": {
        "html": "https://cdn.kscope.io/4d5be67bc105cf4df08769c616be0d6a.html",
        "pdf": "https://cdn.kscope.io/4d5be67bc105cf4df08769c616be0d6a.pdf",
        "word": "https://cdn.kscope.io/4d5be67bc105cf4df08769c616be0d6a.doc",
        "xls": "https://cdn.kscope.io/4d5be67bc105cf4df08769c616be0d6a.xlsx"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 901,
      "limit": 25,
      "offset": 0,
      "has_more": true
    }
  }
}
                                

Holdings

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

                                    import requests

url = "https://api.kscope.io/v2/sec/holdings/320193?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/320193?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Form D - Private Securities Offerings

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Form C - Crowdfunding

Retrieve crowdfunding offering statements filed via Form C.

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Insider Transactions

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

Parameters

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

Example Request

cURL

Python

JavaScript

                                    curl --request GET \
--url 'https://api.kscope.io/v2/insider-v2/320193?key=API-KEY&limit=2' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v2/insider-v2/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-v2/TSLA?key=API-KEY&limit=2",
  "method": "GET",
  "timeout": 0,
};

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Compensation Summary

Fetch summary compensation data for key executives.

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Compensation Director

Retrieve compensation data for company directors.

Parameters

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

Example Request

cURL

Python

JavaScript

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

                                    import requests

url = "https://api.kscope.io/v2/compensation/director/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/director/1214156?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Corporate Actions

Search corporate actions reported in Form 8-K.

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Alerts

Manage email alert subscriptions. Use action=list to retrieve all subscriptions for your key, action=add...

Manage email alert subscriptions. Use action=list to retrieve all subscriptions for your key, action=add to subscribe an email to a content type, or action=delete to remove a subscription.

Parameters

Parameter	Type	Description
action	String	Required. One of: `list`, `add`, `delete`
email_addr	String	Required for `add` and `delete`. The email address to subscribe or unsubscribe.
content	String	Required for `add`. One of: `sec`, `stock`, `prnews`, `sedar`, `weekly`

Example Request

cURL

Python

JavaScript

                                    curl --request GET \
--url 'https://api.kscope.io/v2/ir/sec/alerts?key=API-KEY&action=list' \
--header 'Content-Type: application/json'
                                

                                    import requests

response = requests.get(
    'https://api.kscope.io/v2/ir/sec/alerts',
    params={'key': 'API-KEY', 'action': 'list'}
)
print(response.json())
                                

                                    const params = new URLSearchParams({ key: 'API-KEY', action: 'list' });
fetch(`https://api.kscope.io/v2/ir/sec/alerts?${params}`)
  .then(r => r.json())
  .then(data => console.log(data));
                                

Example Response

JSON

                                    {
  "action": "list",
  "ret": {
    "data": [
      {
        "email_addr": "alerts@example.com",
        "sec": 1,
        "prnews": 0,
        "stock": 0,
        "sedar": 0,
        "weekly": 1
      }
    ]
  }
}
                                

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

M&A Intelligence

Search and filter merger and acquisition deals including acquirer, target, deal type, status, advisors, and transaction value.

1 endpoint

Deal Search

Search M&A deals with filters for acquirer, target, status, deal type, industry, date range, deal value,...

Search M&A deals with filters for acquirer, target, status, deal type, industry, date range, deal value, advisor, CIK, and ticker. Returns paginated results with facet counts grouped by deal type, status, and industry.

Parameters

Parameter	Type	Description
q	String	Search across acquirer and target names
acquirer_q	String	Search acquirer name only
target_q	String	Search target name only
status	String	Filter by status: announced, pending, completed, terminated, withdrawn
deal_type	String	Filter by deal type (e.g. acquisition, merger, takeover)
industry	String	Filter by industry (either side)
acquirer_industry	String	Filter by acquirer industry (comma-separated)
target_industry	String	Filter by target industry (comma-separated)
date_start	String	Start date YYYY-MM-DD
date_end	String	End date YYYY-MM-DD
deal_value_min	Number	Minimum deal value in millions (e.g. 100 = $100M)
deal_value_max	Number	Maximum deal value in millions
advisor	String	Filter by advisor name
cik	String	Filter by SEC CIK number (either side)
ticker	String	Filter by stock ticker (either side)
sort_by	String	Sort field: date, value, acquirer, target, status, deal_type (default: date)
sort_order	String	asc or desc (default: desc)
limit	Int	Results per page (default: 25, max: 100)
offset	Int	Pagination offset (default: 0)

Example Request

cURL

POST

Python

                                    curl --request GET \
--url 'https://api.kscope.io/v2/mergers/deals?key=API-KEY&q=Accenture&status=announced&limit=25' \
--header 'Content-Type: application/json'
                                

                                    curl --request POST \
--url 'https://api.kscope.io/v2/mergers/deals' \
--header 'Content-Type: application/json' \
--data '{"key": "API-KEY", "q": "Accenture", "status": "announced", "limit": 25}'
                                

                                    import requests

url = "https://api.kscope.io/v2/mergers/deals"
payload = {"key": "API-KEY", "q": "Accenture", "status": "announced", "limit": 25}

response = requests.post(url, json=payload)
print(response.json())
                                

Example Response

JSON

                                    {
  "success": true,
  "total": 87,
  "offset": 0,
  "limit": 5,
  "filters_applied": {
    "q": "Accenture"
  },
  "results": [
    {
      "id": "MRG-1B6974182929",
      "announcement_date": "2026-03-03",
      "expected_close_date": null,
      "status": "announced",
      "deal_type": "takeover",
      "transaction_value": null,
      "transaction_value_formatted": "Undisclosed",
      "merger_count": 1,
      "sources_count": null,
      "source": "61d2c0ef4683aefd28b78972db9e576d86a69209",
      "acquirer": {
        "name": "Accenture",
        "ticker": "ACN",
        "cik": 1467373,
        "industry": "IT Consulting and Professional Services",
        "sector": "Other",
        "country": null,
        "state": null,
        "description": "A leading solutions and services company that helps the world's leading enterprises reinvent by building their digital core and unleashing the power of AI to create value at speed across the enterprise."
      },
      "target": {
        "name": "Ookla",
        "ticker": null,
        "cik": null,
        "industry": "Network Intelligence and Analytics",
        "sector": "Other",
        "country": null,
        "state": null,
        "description": "A global leader in network intelligence, competitive benchmarking and customer experience analytics. Headquartered in Seattle, operates a portfolio of brands including Speedtest, Downdetector, Ekahau, and RootMetrics."
      },
      "advisors": [],
      "advisors_summary": {
        "acquirer_financial": [],
        "acquirer_legal": [],
        "target_financial": [],
        "target_legal": []
      },
      "press_release_title": null,
      "press_release_date": null
    }
  ],
  "groups": {
    "deal_type": {
      "horizontal": 65,
      "takeover": 9,
      "vertical": 19,
      "product_extension": 1
    },
    "status": {
      "announced": 47,
      "completed": 44
    },
    "industry": {
      "Professional Services": 33,
      "Professional Services and Technology": 25
    }
  }
}
                                

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status

Stocks

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

3 endpoints

Stock Real-Time enterprise

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Stock Historical enterprise

Retrieve historical stock prices and performance indicators.

Parameters

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

Example Request

cURL

Python

JavaScript

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

                                    import requests

url = "https://api.kscope.io/v2/stock/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/stock-historical?key=API-KEY",
  "method": "GET",
  "timeout": 0,
};

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Stock Delayed enterprise

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

                                    import requests

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

payload={}
headers = {}

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

print(response.text)
                                

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

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Wealth

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

6 endpoints

Search enterprise

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

Inputs

Parameter	Type	Description
key	String	API key (Required)
name	String	Search using a person name. Can be a full or partial name
cik	Integer	Person 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 of residence
limit	Integer	Maximum number of results to return (default: 100, max: 100)

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Gifts enterprise

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

Inputs

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Bios enterprise

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

Inputs

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Sales enterprise

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

Inputs

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Compensation enterprise

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

Inputs

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Holdings enterprise

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

Inputs

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

SEDAR

Access Canadian securities filings via the SEDAR system since 1997.

2 endpoints

SEDAR

Retrieve individual SEDAR filings for Canadian companies.

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

SEDAR Search (v3)

Search Canadian SEDAR filings with rich filtering: ticker/CUSIP/issuer-number identifiers, filing-category...

Search Canadian SEDAR filings with rich filtering: ticker/CUSIP/issuer-number identifiers, filing-category and filing-type filters (with multi-value OR), date ranges, and accurate pagination. Totals reflect the full result set, not just the current page.

Parameters

Parameter	Type	Description
ticker	String	TSX/TSXV ticker symbol (e.g. SHOP). Resolved server-side to the SEDAR issuer number. One identifier required.
symbol	String	Bare or exchange-prefixed symbol (e.g. SHOP, SHOP:CA). Same resolver as ticker.
issuer-symbol	String	Exchange-prefixed symbol (e.g. SHOP:CA). Same resolver as ticker.
issuerno	String	SEDAR issuer number, 9-char zero-padded (e.g. 000037100). Most direct identifier.
cusip	String	6-char CUSIP base (e.g. 82509L). Broader than ticker - matches all share classes for an issuer.
filing_cat	String	Filing category (e.g. CONTINUOUS_DISCLOSURE, securitiesofferings, THIRD_PARTY_FILINGS). Multiple values may be passed separated by ; or , (logical OR).
filing_type	String	Filing type (e.g. NEWS_RELEASES, MANAGEMENT_PROXY_MATERIALS, ANNUAL_FINANCIAL_STATEMENTS). Multi-value supported.
filing_sub	String	Filing sub-type. Multi-value supported.
date_range	String	Shorthand range: 1yr, 3yr, 5yr, 10yr, 20yr, ytd, or all.
year	Int	Restrict to a calendar year (1900-2100).
start	Int	Inclusive lower bound on filing day (days since Unix epoch).
end	Int	Inclusive upper bound on filing day.
limit	Int	Page size (default 20, max 100).
offset	Int	Zero-based row offset for pagination.

Example Request

cURL

Python

JavaScript

                                    curl --request GET \
--url 'https://api.kscope.io/v3/sedar/search?key=API-KEY&ticker=SHOP&filing_type=NEWS_RELEASES;MANAGEMENT_PROXY_MATERIALS&year=2024&limit=10' \
--header 'Content-Type: application/json'
                                

                                    import requests

url = "https://api.kscope.io/v3/sedar/search"
params = {
    "key": "API-KEY",
    "ticker": "SHOP",
    "filing_type": "NEWS_RELEASES;MANAGEMENT_PROXY_MATERIALS",
    "year": 2024,
    "limit": 10
}

response = requests.get(url, params=params)
print(response.json())
                                

                                    const params = new URLSearchParams({
  key: "API-KEY",
  ticker: "SHOP",
  filing_type: "NEWS_RELEASES;MANAGEMENT_PROXY_MATERIALS",
  year: 2024,
  limit: 10
});

fetch(`https://api.kscope.io/v3/sedar/search?${params}`)
  .then(response => response.json())
  .then(data => console.log(data));
                                

Example Response

JSON

                                    {
  "data": [
    {
      "acc": "06216133-00000001-000037100-Final_2024_BFCM_Press_Release-PDF",
      "cusip": "82509L",
      "day": 20060,
      "docid": "674f0570076734002a590041",
      "dt": "2026-05-15T03:28:56",
      "filing_cat": "CONTINUOUS_DISCLOSURE",
      "filing_sub": "NEWS_RELEASES",
      "filing_type": "NEWS_RELEASES",
      "issuerno": "000037100",
      "ts": 1733231984
    },
    {
      "acc": "06202892-00000001-000037100-PR-PDF",
      "cusip": "82509L",
      "day": 20039,
      "docid": "67334e96ae30511d62607535",
      "dt": "2026-05-15T03:28:30",
      "filing_cat": "CONTINUOUS_DISCLOSURE",
      "filing_sub": "NEWS_RELEASES",
      "filing_type": "NEWS_RELEASES",
      "issuerno": "000037100",
      "ts": 1731415702
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "limit": 10,
      "offset": 0,
      "total": 2
    }
  },
  "status": "success"
}
                                

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Press Releases

Access press releases for companies using ticker symbols.

3 endpoints

Press Releases

Fetch the latest press releases by ticker symbol.

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Realtime Transcripts enterprise

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Historical Transcripts enterprise

Fetch historical transcripts with optional filters for ticker, date, date range, call title, and status....

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

Parameters

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

Example Request

cURL

Python

JavaScript

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

Example Response

JSON

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

Rate limit: 3,600 requests/hour

Rolling hourly window · Returns 429 status with reset_in field showing seconds until limit resets

Rate Limits

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

1 endpoint

Rate Limiting Overview

All API endpoints are rate-limited to ensure fair usage and system stability. Rate limits are applied per...

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)

Rate Limit Error Response

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

Handling Rate Limits

Python

JavaScript

cURL

                                    import requests
import time

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

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

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

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

                                    #!/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.

1 endpoint

API Error Codes

The API returns standardized error responses to help you handle issues programmatically. Every error...

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 Response Format

400 Bad Request

401 Unauthorized

429 Rate Limited

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

Robust Error Handling

Python

JavaScript

cURL

                                    import requests
import time
import logging

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

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

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

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

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

fetchData();
                                

                                    #!/bin/bash

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

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

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

Retry Strategy

Exponential Backoff

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

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

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