Research API

Read your own research projects and report summaries from your AI assistant or a tool you run yourself.
Who can use it

The Research API is available on the Space Analyst plan and above. It is available on personal AstraEye Labs accounts only, not on an account provided through a school or another institution.

On the free plan, a connected assistant reads your own reports and the public research library and turns Earnings Radar on or off for a stock you name; everything else it can do needs a plan that includes the Research API.

What it returns is the written prose of your own reports: the executive summary, the discussion, the conclusion, the prepared questions and answers and, where a report has them, its methodology and its test. It never returns charts, tables or data fields. By default it can only read. With the SAGE chat permission and a daily credit limit you set, it can also talk to SAGE and let SAGE act for you, including running research, within that limit.

Start freeSee plans
Use it with your AI assistant

You can connect AstraEye to ChatGPT, Claude, Gemini, Perplexity, Grok or Glama. Each connection is made from the assistant: you sign in to AstraEye when it asks and choose what it may do.

Each of them connects to the same remote MCP server (Model Context Protocol), listed in the MCP Registry as io.astraeyelabs/research. Its public description is on GitHub.

Step by step: How to use it in ChatGPT.

Step by step: How to use it in Claude.

In ChatGPT, open Plugins, search for AstraEye Labs and install it, or open it directly. Then sign in to AstraEye when it asks and choose what ChatGPT may do. It is separate from your token.

Open in ChatGPT

Alternatively, with Claude Code, or any AI assistant setup that can run commands on your computer, use a personal token:

  1. Create a token in Settings → Research API.
  2. Keep it on your computer as an environment variable named ASTRAEYE_TOKEN, so it is never pasted into the conversation.
  3. Ask your assistant, for example:
Using curl with the header "Authorization: Bearer $ASTRAEYE_TOKEN",
list my reports from https://astraeyelabs.io/api/v1/research/reports,
fetch the latest one, and let's discuss today's market research results.

Your token works only on your own account, and with the SAGE chat permission it can also spend your Astra Credits, so keep it to yourself. Do not paste it into a chat or share it, and revoke it in settings if it is ever exposed. What your assistant reads is for your own research: the sources and disclosures in each report stay with it, and the content is informational, not advice. Terms Section 14.1 sets out exactly what is permitted.

Overview

By default the Research API is read-only: it provides programmatic access to your own research projects, to the written prose of each of your finished reports, and to the catalog of analyses and research templates AstraEye offers, with the plan each is on. If a token has the SAGE chat permission (sage:chat) and a positive daily credit limit,it can also ask SAGE questions in your SAGE conversation, and take actions of its own: change your watchlist and research projects, price, start and stop research runs, and refresh your connected balances, each a separate request, spending Astra Credits within that limit. It can never set up or change a schedule, change your settings, security, billing or email, or place or route an order.

Use of this API is governed by Section 14.1 of the Terms of Service, which grants access for your own personal, non-commercial research and for no other purpose. Sections below cite the governing provision wherever a technical rule carries a corresponding contractual obligation.

What research covers

AstraEye researches crypto and U.S. stocks and ETFs. In the catalog, ETFs belong to the equity asset class with stocks. Analyses about companies (fundamentals, earnings, insider and institutional filings, and analyst actions) describe an operating company and do not describe an ETF, so for ETFs choose analyses of price, volatility, options, distributions and news. Each analysis states the kinds of security it can describe in securityTypes; one that lists only stock is not run for a fund, and a run that holds funds is charged for it on its stocks only, or not at all when it holds no stocks.

Commodities are covered only through commodity ETFs, such as GLD and IAU for gold, SLV for silver, USO for crude oil, UNG for natural gas, CPER for copper, and DBC or PDBC for a broad basket. Research on one describes the fund, which can drift from the commodity it tracks, most of all for funds that hold futures. Commodity prices and futures themselves are not covered. The global market draws its stocks from company indexes, so to research ETFs, name them or add them to your watchlist.

Obtaining a token

Tokens are issued from Settings → Research API. The token value is displayed once at creation and is not recoverable afterwards. One token may be active per account, and each token expires 90 days after issue. A connection to an AI assistant such as Claude or ChatGPT is separate: it does not count as this token and does not use one.

Under Terms Section 14.1 the token is personal to you. It must be kept confidential and must not be shared, published, sold, transferred, or sublicensed. You are responsible for all activity conducted with it. If a token is exposed, revoke it in settings and issue a replacement, which invalidates the previous token immediately.

Authentication

Authenticate every request to the endpoints below with your token as a bearer credential. A connection to an AI assistant signs in through that assistant instead; its credentials do not work on these endpoints, and your token does not work for a connection.

curl https://astraeyelabs.io/api/v1/research/projects \
  -H "Authorization: Bearer $ASTRAEYE_TOKEN"
Headers
NameInTypeRequiredDefaultDescription
AuthorizationheaderstringrequirednoneBearer <token>. Requests without a valid credential return 401.

Automated access is permitted only through this API and within the published limits stated below, in accordance with Terms Section 14.

List research projects
GET/api/v1/research/projects

Returns the research projects belonging to the authenticated account, ordered newest first. Archived projects are never returned.

Query parameters
NameInTypeRequiredDefaultDescription
statusquerystringoptionalactiveLifecycle state to return: "active", "paused", or "all" for both. Archived projects are not returned, and any other value is refused with a 400.
cursorquerystringoptionalnoneOpaque cursor from a previous response's nextCursor. Returns the page immediately after it. Omit for the first page.
limitqueryintegeroptional20How many projects to return per page, from 1 to 50.
Response fields
FieldTypeDescription
hasMorebooleanTrue when more projects exist beyond this page.
nextCursorstring | nullPass as cursor to retrieve the next page. Null on the last page.
projects[].idstringProject identifier. Use as researchId when listing reports.
projects[].titlestringProject title as shown in the Lab.
projects[].statusstringCurrent lifecycle state.
projects[].createdAtstring (ISO 8601)When the project was created.
projects[].updatedAtstring (ISO 8601)When the project last changed.
projects[].runCountintegerNumber of runs the project has performed.
projects[].lastRunAtstring (ISO 8601) | nullWhen the project's most recent run started. Null if it has never run.
projects[].scheduledbooleanWhether the project has a schedule attached.
{
  "hasMore": false,
  "nextCursor": null,
  "projects": [
    {
      "id": "…",
      "title": "Crypto majors, weekly",
      "status": "active",
      "createdAt": "2026-08-01T09:14:22.000Z",
      "updatedAt": "2026-08-24T09:14:22.000Z",
      "runCount": 12,
      "lastRunAt": "2026-08-24T09:00:00.000Z",
      "scheduled": true
    }
  ]
}

Returns 20 projects per page unless you set limit (at most 50), ordered newest first. Continue by passing nextCursor as cursor until hasMore is false.

List reports
GET/api/v1/research/reports

Returns an index of finished reports, ordered by generation time, newest first. A report corresponds to one run group, the unit shown on the results page. Only reports in a ready state are returned; pending, generating, failed, and degraded groups are omitted because they carry no dependable summary. Reports of archived projects are not returned, in this list or by id. The first report is the most recently finished run.

Query parameters
NameInTypeRequiredDefaultDescription
researchIdquerystringoptionalnoneRestrict the result to a single project. Accepts a projects[].id value. Omit to list reports across all projects.
cursorquerystringoptionalnoneOpaque cursor from a previous response's nextCursor. Returns the page immediately after it. Omit for the first page.
limitqueryintegeroptional20How many reports to return per page, from 1 to 50.
Response fields
FieldTypeDescription
hasMorebooleanTrue when more reports exist beyond this page.
nextCursorstring | nullPass as cursor to retrieve the next page. Null on the last page.
reports[].idstringReport identifier. Use to retrieve the summary.
reports[].researchIdstringIdentifier of the project the report belongs to.
reports[].urlstring | nullThe report's page in AstraEye, with its charts and figures. It opens only for you when signed in. Null if the address cannot be formed.
reports[].generatedAtstring (ISO 8601) | nullThe single point in time at which the report was generated, and the field the list is ordered by. This is not a range. Null where a generation timestamp was not recorded.
reports[].availableLanguages[]string[]Languages this report can be read in, "en" first. Pass one as the language parameter when retrieving the summary, methodology or test. A report with no purchased translation lists "en" alone.
{
  "hasMore": false,
  "nextCursor": null,
  "reports": [
    { "id": "…", "researchId": "…", "generatedAt": "2026-08-24T09:31:00.000Z",
      "url": "https://astraeyelabs.io/research/…/results/…",
      "availableLanguages": [ "en", "ru" ] }
  ]
}

Returns 20 reports per page unless you set limit (at most 50). Continue by passing nextCursor as cursor until hasMore is false. The cursor resumes right after the last report you received, so a report generated between two requests cannot push an older one across a page boundary and hide it. Terms Section 14.1 prohibits using repeated or scheduled requests to accumulate content into a dataset or to reconstruct an underlying provider dataset.

List analyses
GET/api/v1/research/analyses

Returns the analyses AstraEye can run: the same list as the analysis catalog, with the id SAGE understands. An assistant can use it to name an analysis precisely when it asks SAGE what an analysis measures or asks SAGE to run one. Each analysis states the plan it is on and whether your plan includes it, and the response states your own plan. Prices are not listed: they depend on the run, and SAGE states them when asked.

Query parameters
NameInTypeRequiredDefaultDescription
scientistquerystringoptionalnoneOnly this scientist's analyses, by scientist id, such as atlas.
assetClassquerystringoptionalnoneOnly analyses for "crypto", "equity" or "universal" (both).
detailquerystringoptionalsummary"summary" returns the one-line summary of each analysis. "full" adds the full description, which is long; combine it with scientist or assetClass.
Response fields
FieldTypeDescription
countintegerNumber of analyses returned.
yourPlanobject | nullYour current plan. Null where it cannot be stated, such as an account with no plan.
yourPlan.idstringThe plan id.
yourPlan.namestringThe plan name members see on the subscribe page, such as Space Analyst.
yourPlan.rankintegerThe plan's position in AstraEye's plan order. A higher number is a higher plan; compare yourPlan.rank with an item's plan.rank.
analyses[].idstringThe analysis id, such as ta_momentum_scan. Use it, or the name, with SAGE.
analyses[].namestringThe analysis name as the catalog shows it.
analyses[].scientiststringThe scientist that runs it, such as atlas.
analyses[].assetClass"crypto" | "equity" | "universal"What it analyses: crypto runs only on crypto and equity only on stocks and ETFs; universal covers both. An analysis with no asset of its class in a project is skipped and not charged. Which kinds of security it can describe is securityTypes; see What research covers.
analyses[].summarystring | nullOne-line description.
analyses[].readsEarlierFindingsbooleanTrue when the analysis works from what other analyses found, such as LYRA's consensus. It only sees analyses that finished before it, so it belongs in a later stage or a later phase than them.
analyses[].needsstring[]Present when specific analyses must run before this one: their ids.
analyses[].securityTypes("stock" | "etf" | "mutual_fund")[]The kinds of security it can describe. An analysis about companies (fundamentals, earnings, insider and institutional filings, analyst actions, sector rank) lists only "stock": it is not run for an ETF or a mutual fund, and a run is not charged for one. Absent for a crypto-only analysis.
analyses[].descriptionstring | nullFull description of what it does. Present only with detail="full".
analyses[].planobject | nullThe lowest plan that includes this analysis: id, name and rank, as in yourPlan. Null where it cannot be stated.
analyses[].includedInYourPlanboolean | nullWhether your plan includes this analysis. Null where it cannot be determined, which is not the same as false.
{
  "count": 1,
  "yourPlan": { "id": "analyst", "name": "Space Analyst", "rank": 1 },
  "analyses": [
    { "id": "ta_momentum_scan", "name": "Momentum Scan", "scientist": "atlas",
      "assetClass": "universal", "summary": "…", "description": "…",
      "plan": { "id": "freelancer", "name": "Freelancer", "rank": 0 },
      "includedInYourPlan": true }
  ]
}

With SAGE chat, an assistant can pass an analysis by name or id straight to SAGE, for example: "Ask SAGE to explain what the Momentum Scan measures" or "Ask SAGE to run a Momentum Scan on my watchlist". SAGE quotes the price first.

Retrieve an analysis
GET/api/v1/research/analyses/{id}

Returns one analysis in full, by its id from the list: its name, scientist, asset class, full description and methodology, meaning how it works, the public theory it rests on and what that theory cannot support. Load it when a conversation needs more than the one-line summary. Like the list, it states the plan the analysis is on, whether your plan includes it, and your own plan.

Response fields
FieldTypeDescription
analysis.id, name, scientist, assetClass, summarystringAs in the list. summary may be null.
analysis.securityTypes("stock" | "etf" | "mutual_fund")[]As in List analyses.
analysis.descriptionstring | nullFull description of what it does.
analysis.methodologystring | nullHow the analysis works and the limits of its method. Null where none is published.
analysis.plan, includedInYourPlanobject | null; boolean | nullAs in the list.
yourPlanobject | nullYour current plan: id, name and rank, as in the list.

An id that is not in the catalog returns 404 not_found.

List templates
GET/api/v1/research/templates

Returns the research templates AstraEye offers: prebuilt combinations of analyses you can start a research project from, as the template gallery shows them. Each names the scientists and analyses it combines, the plan it is on and whether your plan includes it, and the response states your own plan. An assistant can use it to find the template that covers a question. Prices are not listed; SAGE states them when asked.

Query parameters
NameInTypeRequiredDefaultDescription
assetClassquerystringoptionalnoneOnly templates whose asset class is exactly "crypto", "equity" or "universal" (both).
scientistquerystringoptionalnoneOnly templates that include this scientist, by scientist id, such as atlas.
analysisquerystringoptionalnoneOnly templates that include this analysis, by its id from the analysis list.
Response fields
FieldTypeDescription
countintegerNumber of templates returned.
yourPlanobject | nullYour current plan: id, name and rank, as in List analyses.
templates[].idstringThe template id. Pass it to Retrieve a template.
templates[].namestringThe template name as the gallery shows it.
templates[].summarystring | nullOne-line description.
templates[].categorystring | nullThe gallery category, such as technical, fundamental or sentiment.
templates[].assetClass"crypto" | "equity" | "universal"What it analyses; universal covers both. Each of its analyses runs only on assets of its own class.
templates[].scientists[]{ id, name }The scientists whose analyses it combines, by id and name.
templates[].analyses[]{ id, name }The analyses it runs, by analysis id and the name the template gives it. Each id can be read with Retrieve an analysis.
templates[].planobject | nullThe lowest plan that includes this template: id, name and rank. Null where it cannot be stated.
templates[].includedInYourPlanboolean | nullWhether your plan includes this template. Null where it cannot be determined, which is not the same as false.
{
  "count": 1,
  "yourPlan": { "id": "analyst", "name": "Space Analyst", "rank": 1 },
  "templates": [
    { "id": "tmpl_v2_equity_fundamentals", "name": "Equity Deep Fundamentals",
      "summary": "…", "category": "fundamental", "assetClass": "equity",
      "scientists": [{ "id": "felix", "name": "FELIX" }],
      "analyses": [{ "id": "fundamental_cash_flow_quality", "name": "Cash Flow Quality" }],
      "plan": { "id": "trader", "name": "Galactic Merchant", "rank": 2 },
      "includedInYourPlan": false }
  ]
}

A template that is not included in your plan is still listed, with includedInYourPlan false, so an assistant can tell you which plan includes it.

Retrieve a template
GET/api/v1/research/templates/{id}

Returns one template in full, by its id from the list: its full description, typical cadence and duration, and the analyses it runs, in order, each with the analysis id that Retrieve an analysis reads. Analyses in the same phase run side by side, grouped into workstreams, and a later phase starts once every earlier phase has finished. Within a workstream, a later stage starts once its earlier stages have finished.

Response fields
FieldTypeDescription
yourPlanobject | nullYour current plan: id, name and rank, as in the list.
template.id, name, summary, category, assetClass, scientists, plan, includedInYourPlanas in the listAs in the list.
template.descriptionstring | nullFull description of what the template is for.
template.complexitystring | nullThe gallery's complexity label, such as starter or advanced.
template.recommendedCadencestring | nullHow often the template is meant to be run, such as Daily or Weekly.
template.estimatedMinutesinteger | nullTypical time for a run to finish, in minutes.
template.analysisCountintegerNumber of analyses the template runs.
template.analyses[].id, name, scientiststringThe analysis, by id, name and scientist.
template.analyses[].phaseinteger | null1 for the first phase. Every earlier phase finishes before a later one starts.
template.analyses[].workstreamstring | nullThe group of analyses this one runs in within its phase.
template.analyses[].stageinteger | null1 for the first stage of its workstream. A workstream's earlier stages finish before a later one starts; analyses in the same stage run together.
template.analyses[].stageLabelstring | nullThe label the template gives that stage.

An id that is not a current template returns 404 not_found.

Retrieve a project
GET/api/v1/research/projects/{id}

Returns one of your projects, by its id from List research projects, as it will run: every analysis with its phase, workstream and stage, in the same terms as Retrieve a template, and what the project covers. Analyses in the same stage run together; a later stage starts once the earlier ones have finished; workstreams in the same phase run side by side and cannot use each other's findings, and a later phase can use all of them. Use it to check that a project set up through SAGE has the structure you asked for.

Response fields
FieldTypeDescription
project.id, title, statusstringThe project, as in the list.
project.covers.kind"global_market" | "chosen_assets" | "watchlist" | "holdings_or_watchlist"What the project covers.
project.covers.coveragestringOn the global market: which asset classes it covers, by the coverage choice's name (Crypto and stocks, Stocks only or Crypto only; see List market slices).
project.covers.marketSlicesstring[]On the global market: the slice ids it draws from (see List market slices). Empty means each asset class's default.
project.covers.marketSliceNamesstring[]The same slices by name, in the same order, as List market slices names them.
project.covers.skipsAssetClass"crypto" | "equity" | nullOn the global market: an asset class the project leaves out.
project.analyses[].id, name, scientiststringThe analysis, by id, name and scientist.
project.analyses[].phase, workstream, stage, stageLabelas in Retrieve a templateWhere the analysis runs.
project.analyses[].readsEarlierFindingsbooleanAs in List analyses.

An id that is not one of your projects returns 404 not_found.

List a project's runs
GET/api/v1/research/projects/{id}/runs

The runs of one of your projects, newest first, one page at a time: each run's id, status and times, and whether its report can be read. How far along a run is comes from Retrieve a run. Pass nextCursor back as cursor while hasMore is true; limit is 1 to 50 (default 20).

Response fields
FieldTypeDescription
hasMore, nextCursorboolean, string | nullPaging, as in List research projects.
runs[].runGroupIdstringThe run's id. It is also its report's id.
runs[].projectIdstringThe project it ran.
runs[].statusstringpending or running while it works; then one of completed, completed_partial, failed, skipped, cancelled, not_started.
runs[].finishedbooleanWhether the run will not change again.
runs[].startedAt, finishedAtstring | nullISO 8601 times; finishedAt only once finished.
runs[].resultsReadybooleanA finished run whose report can be read, by the same id, with Retrieve a report.

An id that is not one of your projects returns 404 not_found.

Retrieve a run
GET/api/v1/research/projects/{id}/runs/{runGroupId}

One run of one of your projects: what it is doing, how far along it is, and whether its report can be read. Progress is the figure AstraEye's own progress bar shows: an analysis that failed or was skipped counts as done, so a finished run is never stuck short of 100, and the figure never goes backwards.

Response fields
FieldTypeDescription
run.runGroupIdstringThe run's id. It is also its report's id.
run.projectIdstringThe project it ran.
run.statusstringpending or running while it works; then one of completed, completed_partial, failed, skipped, cancelled, not_started.
run.finishedbooleanWhether the run will not change again.
run.startedAt, finishedAtstring | nullISO 8601 times; finishedAt only once finished.
run.progress.percentnumber | null0 to 100, as AstraEye's progress bar shows it; null when it cannot be measured yet.
run.progress.done, totalnumberUnits of work finished and in all, the bar's own count.
run.analyses[]object[]Every analysis dispatched for the run, in run order: id, name, scientist, status (pending, running, completed, failed, skipped or cancelled), part (analysis, or report for a step of SAGE writing the report) and reused. Empty before the first is dispatched.
run.resultsReadybooleanA finished run whose report can be read, by the same id, with Retrieve a report.

A run that is not one of that project's runs, or a project that is not yours, returns 404 not_found.

Tracking a run

When SAGE starts research through Send a message, the run_start action carries the run's runGroupId and its projectId. To follow it:

  1. Keep both ids. For a run you did not start, find it with List a project's runs.
  2. Read Retrieve a run. While finished is false the status is pending or running and progress.percent says how far along it is; null means it cannot be measured yet, not zero. Runs take minutes, so check again after a pause rather than in a tight loop.
  3. When finished is true the status is one of completed, completed_partial, failed, skipped, cancelled, not_started. If resultsReady is true, read the report with Retrieve a report, using the same runGroupId as the report id.
  4. A run SAGE started also posts a message when it finishes: in Read messages it has kind run_delivery and the same runGroupId and projectId.
List market slices
GET/api/v1/research/market-slices

The parts of the market a project or run on the global market can be drawn from, such as the largest 25 S&P 500 companies, a sector or the top 100 coins, with the rule that decides what each one includes. Every slice is listed, in AstraEye's order: by market cap from the narrowest up, then the other groups.

The Funds slices (commodity funds, sector funds and broad market funds) hold exchange-traded funds rather than companies. A run on one reads each fund's own shares, and the analyses that describe operating companies, such as fundamentals, earnings and insider filings, do not run on it and are not charged.

A project or run covers at most one slice of each asset class: one stocks slice, one crypto slice, or one of each (for example the S&P 500 and the top 100 coins). To research several slices of the same asset class, such as two sectors or the S&P 500 and the Dow 30, create one project per slice: each project draws your plan's full number of assets from its own slice, so every slice gets complete coverage. When you ask SAGE, name each slice exactly as listed here.

A project on the global market also covers crypto and stocks, stocks only or crypto only. The response names those three choices in coverageChoices, the way the project page does; name the one you want to SAGE in the same words, beside the slice, for example "the global market, Stocks only, Largest 10 by market cap". Which assets a slice holds is decided when a run starts and is not listed here; the report names them.

Response fields
FieldTypeDescription
marketSlices[].idstringThe slice id, such as equity_sp500.
marketSlices[].namestringThe slice name, such as S&P 500.
marketSlices[].assetClass"crypto" | "equity"The asset class it draws.
marketSlices[].groupobject | nullThe section it is listed under: id and label, such as By market cap, Indexes, Sectors or Funds. Slices of one group are listed together.
marketSlices[].rulestringWhat the slice includes, in plain words.
marketSlices[].filterobjectThe same rule as fields: index (a membership list), rankMax (a market-cap rank ceiling; for stocks, the company's rank within the index, each company counted once), minTurnover (a trading-volume floor) and tickers (a fixed list of funds AstraEye keeps, such as the sector funds). An absent field does not narrow.
marketSlices[].defaultbooleanTrue for the slice an asset class draws from when none is chosen.
marketSlices[].planobject | nullThe lowest plan that can use this slice: id, name and rank, as in List analyses. Null where it cannot be stated.
marketSlices[].includedInYourPlanbooleanWhether your plan can use this slice.
yourPlanobject | nullYour current plan: id, name and rank.
coverageChoices[].namestringCrypto and stocks, Stocks only or Crypto only: which asset classes a global-market project covers, named as the project page names it.
coverageChoices[].detailstringWhat the choice gives, in plain words.
coverageChoices[].assetClasses("crypto" | "equity")[]The asset classes it draws.
coverageChoices[].skipsAssetClass"crypto" | "equity" | nullThe class it leaves out, as project.covers.skipsAssetClass states it.
Retrieve a report summary
GET/api/v1/research/reports/{id}

Returns the written summary of a single finished report belonging to the authenticated account.

Path parameters
NameInTypeRequiredDefaultDescription
idpathstringrequirednoneReport identifier from reports[].id. A report that does not belong to the account returns 404.
Query parameters
NameInTypeRequiredDefaultDescription
languagequerystringoptionalenThe language to return the prose in. Responses are English unless this is passed, so an existing integration is unaffected. Accepts any value from the report's availableLanguages, and a regional form such as en-US resolves to its base language. A language the report does not have returns 400 unsupported_language rather than quietly returning English.
Response fields
FieldTypeDescription
report.idstringReport identifier.
report.researchIdstringIdentifier of the project the report belongs to.
report.urlstring | nullThe report's page in AstraEye, with its charts and figures. It opens only for you when signed in. Null if the address cannot be formed.
report.generatedAtstring (ISO 8601) | nullWhen the report was generated.
report.languagestringThe language of the prose in this response. This is what was actually served, which is not always what was requested - see requestedLanguage below.
report.availableLanguages[]string[]Every language this report can be read in, "en" first.
report.coverage"complete" | "partial"Whether every piece of prose in this response reached report.language. A translation frequently settles partially, so "partial" is ordinary rather than exceptional: read the per-item language field to see which pieces did, and englishParagraphs for paragraphs inside a translated piece that stayed in English.
report.requestedLanguagestring (present only on a fallback)The language that was asked for, when it could not be served and English was returned instead. Absent on an ordinary response, so its presence is the signal.
report.languageFallbackReasonstring (present only on a fallback)Why the requested language was not served: family_not_translated (this part of the report was not translated), no_translated_units (nothing in this part reached that language), unit_metadata_unavailable (the per-item language record could not be read or verified, so the prose is not presented as translated), or translated_artifact_unreadable.
report.summary.titlestring | nullSummary title.
report.summary.titleLanguagestring | nullThe language this piece of prose was actually written in. Null where it is not recorded, which is not the same as English - the language is unknown, and the field says so rather than guessing.
report.summary.executiveSummarystring | nullOpening prose summary.
report.summary.executiveSummaryLanguagestring | nullThe language of the opening prose, on the same terms as titleLanguage.
report.summary.sections[]objectOrdered sections, each { id, heading, body, scientistId, language }. Only body is always present; the others may be null.
report.summary.sections[].englishParagraphsobject (present only when some paragraphs are in English)Paragraphs that stayed in English inside a section whose language is the translation's, as { body: [positions] }. A position counts the body's paragraphs, split on blank lines, from 0. A translated paragraph is kept in English when it could not be published as translated; the rest of the section is still translated, and coverage reads "partial".
report.summary.sections[].captionsarray (present only when the section has some)Fixed captions that belong with a paragraph of the body, each { analysisTypes[], afterParagraph, lines[] { language, text } }. Show every line, in order and unchanged, directly after the paragraph at position afterParagraph (counted as for englishParagraphs), or before the body when afterParagraph is null; never in a tooltip, a footnote or a separate page. Today the one caption marks a simulated result (an indicator rule tested on the past closing prices of a crypto asset or of a fund's shares): a statement in English and a line naming what was tested, followed by their translation when the response is translated. Captions are not part of body, so the section's language does not describe them; each line states its own.
report.summary.conclusionstring | nullClosing prose.
report.summary.conclusionLanguagestring | nullThe language of the closing prose, on the same terms as titleLanguage.
report.summary.questions[]objectPrepared questions and answers, each { id, question, answer, scientistId, language }. scientistId and language may be null.
report.summary.questions[].englishParagraphsobject (present only when some paragraphs are in English)As on a section, for the answer: { answer: [positions] }.
report.summary.englishParagraphsobject (present only when some paragraphs are in English)As on a section, for the opening and closing prose: { executiveSummary: [positions], conclusion: [positions] }, each present only when it has some.
report.summary.captionsobject (present only when there are some)Captions outside the sections, as on a section: { executiveSummary: [captions], conclusion: [captions], sections: [captions] }, each present only when it has some. Those under executiveSummary and conclusion follow the field's last paragraph; those under sections are shown before the first section.
report.summary.disclosuresobjectInformational notice, provenance statement, source list, notAdvice flag, and whether SAGE declined the advice part of the run. See Disclosures below.
{
  "report": {
    "id": "…",
    "researchId": "…",
    "generatedAt": "2026-08-24T09:31:00.000Z",
    "url": "https://astraeyelabs.io/research/…/results/…",
    "language": "ru",
    "availableLanguages": [ "en", "ru" ],
    "coverage": "partial",
    "summary": {
      "title": "…",
      "titleLanguage": "ru",
      "executiveSummary": "…",
      "executiveSummaryLanguage": "en",
      "sections": [ { "id": "…", "heading": "…", "body": "…", "scientistId": "…",
                      "language": "ru",
                      "captions": [ { "analysisTypes": [ "…" ], "afterParagraph": 1,
                                      "lines": [ { "language": "en", "text": "…" },
                                                 { "language": "ru", "text": "…" } ] } ] } ],
      "conclusion": "…",
      "conclusionLanguage": null,
      "questions": [ { "id": "…", "question": "…", "answer": "…", "scientistId": "…",
                       "language": "ru" } ],
      "disclosures": {
        "informationalNotice": "…",
        "provenanceDisclosure": "…",
        "sources": { "notice": "…", "url": "…/data-sources", "credits": [ "…" ] },
        "notAdvice": true,
        "adviceDeclined": false
      }
    }
  }
}
Retrieve a report methodology
GET/api/v1/research/reports/{id}/methodology

Returns how each analysis in the report was carried out, in written prose. Many reports have no methodology section; those return 404 not_found. Takes the same id and language parameters as the summary.

Response fields
FieldTypeDescription
methodology.reportId, researchId, generatedAtstring; generatedAt string | nullAs on the summary.
methodology.language, availableLanguages, coveragestring, string[], "complete" | "partial"The same language fields as the summary, including requestedLanguage and languageFallbackReason on a fallback.
methodology.analyses[]objectEach { analysisType, title, scientistId, theorySource, sections[] { heading, body, englishParagraphs, captions }, language }. Only body is always present; the others may be null, and englishParagraphs is present only when part of a section stayed in English inside a translated analysis, as on a summary section ({ heading: [positions], body: [positions] }). An analysis with no written method is left out. theorySource says whether the method comes from a written explanation of the analysis or from the run's own findings. A section's captions, present only when it has some, are shown after its paragraph at afterParagraph, as on a summary section.
Retrieve a report test
GET/api/v1/research/reports/{id}/quiz

Returns the multiple-choice test written from the report, where it has one; a report without a test returns 404 not_found. Takes the same id and language parameters as the summary. Answers stay hidden until you submit that scientist's part of the test in AstraEye.

Response fields
FieldTypeDescription
quiz.reportId, researchId, generatedAtstring; generatedAt string | nullAs on the summary.
quiz.language, availableLanguages, coveragestring, string[], "complete" | "partial"The same language fields as the summary, including requestedLanguage and languageFallbackReason on a fallback.
quiz.submittedScientists[]string[]The scientists whose part of the test you have submitted. "*" means the whole test was submitted at once.
quiz.questions[]objectEach { id, scientistId, source, question, choices[], correctIndex, explanation, answerAvailable, language, englishParagraphs }. scientistId, source and language may be null. While that part of the test is open, answerAvailable is false and correctIndex and explanation are null; explanation can also be null after it is submitted. englishParagraphs is present only when part of a translated question stayed in English, as on a summary section, keyed question, choices.N or explanation (the last only while the explanation is shown).
Scope of returned content

Responses contain written prose only: the summary presented on the results page, and the report's methodology and test where it has them. Charts, tables, figures, numeric series, screener output, and underlying market data are not exposed through this API.

Content returned is AstraEye Labs derived research output. It is not raw or redistributed market data, and receipt of it conveys no license, right, title, or interest in any data provider's data. Terms Section 12 continues to govern provider-sourced material, and Section 14.1 confirms that this API is not a data-export feature within the meaning of any provision of Section 12 governing the export of a provider's data. The restrictions in Section 12 applicable to derived output, including the prohibitions on model training and on reconstructing an underlying provider dataset, apply in full.

Permitted use

Terms Section 14.1 authorizes you to make your own research summaries available to an artificial-intelligence assistant, agent, or other tool that you personally operate and control, for your own personal research purposes. That authorization is expressly limited and does not permit:

  • using the content to develop, train, fine-tune, evaluate, or improve any model;
  • retaining or accumulating the content beyond what your personal use requires, or assembling it into a dataset, index, archive, or corpus;
  • using repeated or scheduled requests to reconstruct or approximate any underlying provider dataset;
  • making the content available to any other person, including through a shared workspace, assistant, channel, or published output; or
  • using the content to build, market, operate, or support any product or service.

You are responsible for the tool you select and for its handling of content you transmit to it. Before transmitting content, satisfy yourself that the tool's terms and data practices are consistent with your obligations, including that it does not train on, retain, or redistribute what it receives.

Disclosures and attribution

Each report carries a disclosures object containing an informational notice, a provenance statement, and the source list, provided as structured fields so a client can present them correctly.

adviceDeclined is true when the run was read as a request for advice and SAGE declined that part before giving facts. It is reported as a field rather than as a sentence inside the summary prose, so a client can surface it in its own right; the summary itself always begins with findings.

Under Terms Section 14.1 these must not be removed, altered, obscured, suppressed, or detached from the content they accompany, and must be preserved wherever the content is displayed or read back. AstraEye Labs research is informational and educational only. It is not financial, investment, legal, or tax advice, is not a recommendation or solicitation, and is not personalized to your circumstances. Terms Sections 3 and 4 apply in full to all content returned by this API.

SAGE chat (optional permission)

A token created with the SAGE chat permission (sage:chat) can also send text to your own SAGE conversation and read the replies. Messages sent this way appear in your SAGE chat on the web and in the app. Each reply is a SAGE answer and costs Astra Credits as one does, up to the daily credit limit you set when creating the token; limits reset at 00:00 UTC. SAGE only answers here: a message is a question, and SAGE starts, prices and changes nothing because of it. Changes are the separate action requests described below, which your tool makes itself. When a run finishes, the result arrives in the same conversation.

POST/api/v1/sage/messages
FieldTypeDescription
clientMessageIdstring (UUID)A new id you generate for each message. Resending the same id returns the same turn instead of asking again; reusing it for a different message returns 409.
textstringYour message: up to 1,000 characters, and not blank.
conversationIdstring (UUID), optionalA conversation returned by this API. Omitted, your current SAGE conversation is used.

Waits up to 50 seconds for the reply. Returns 200 with { turnId, conversationId, status: "completed", reply: { role, text } }, or 202 with status: "generating" when the answer is still being written.

GET/api/v1/sage/turns/{turnId}

The state of one turn: generating, completed (with reply) or failed.

GET/api/v1/sage/messages

Messages in a conversation, oldest first. Parameters: conversationId (optional), cursor (from nextCursor, to receive only newer messages) and limit (1 to 50, default 20). Each message has id, role, text, createdAt, ordinal and kind: run_delivery (with runGroupId) for a finished run's result, chat otherwise. delivery: "unavailable" means finished runs could not be checked on this call; try again shortly.

Asking SAGE

Through your connected assistant the tool is ask_sage; with a token, POST /api/v1/sage/messages. Say it the way you would in the app. For example:

  • Understand your research: "Ask SAGE what my latest report says about Bitcoin's momentum", or "how the Momentum Scan reached its result".
  • Choose what to run: "Ask SAGE which analysis would show who is holding ETH", or "what the Crypto Perpetuals Positioning template would tell me about BTC".
  • Read first, then ask: "Read my latest report, then ask SAGE what its most important finding is". Your assistant reads your reports itself and brings the question to SAGE.
  • Learn the concepts: "Ask SAGE what the RSI measures".
  • In your language: ask in English, Russian or Spanish, and SAGE answers in the same language.

SAGE explains research and never tells you what to buy or sell. When a message asks for a change, SAGE says so and names the action that makes it; it does not make it. Schedules and support requests are handled in AstraEye on the web or in the SAGE app.

ChatGPT, for now: until ChatGPT supports the separate actions, a ChatGPT connection's messages to SAGE can still act as they did before, as Terms Section 14.1 describes: what a message asks for outright happens at once, and what SAGE proposes happens when the next message agrees, carrying pendingAction and actions on the reply. This ends when ChatGPT supports the separate actions.

Actions

With the SAGE chat permission your tool can change your research itself, one separate request per action, each carried out at once. Through a connected assistant each action is a tool of the same name, described to the assistant for what it does, so it can ask you before it calls one; whether it asks is set in the assistant. Every action is recorded and shown in your API activity in Settings. Assets are named by assetId, projects by projectId, analyses and templates by their ids from the catalog.

Find assets and your watchlist
GET/api/v1/assets/lookup?name={name}&name={name}

find_assets. One to 20 names or tickers, repeated as name. Each comes back found with its asset, choose with candidates when several assets share it (ask which one), or not_found with a reason. An asset is { assetId, symbol, name, assetClass, kind, onWatchlist }, where kind is crypto, stock, etf or mutual_fund.

GET/api/v1/watchlist

list_watchlist. The assets on your watchlist, each as above. Never a quantity, cost basis or note. Research covers only watchlist assets.

Change your watchlist
POST/api/v1/watchlist/add

add_to_watchlist. { assetIds } (1 to 25), or { marketSliceId } for every member of a market slice with a fixed list. All are added together, or none. Returns added, and alreadyDone for any already there.

POST/api/v1/watchlist/remove

remove_from_watchlist. { assetIds }. Removing an asset also deletes the quantity, cost basis and note you recorded for it. All are removed together, or none.

Research projects
POST/api/v1/research/projects/create

create_research_project. title, the work (analysisIds or a templateId), covers (chosen_assets with assetIds, watchlist, holdings_or_watchlist, or global_market with marketSliceIds and skipsAssetClass), and optionally a description and reportOptionsOn ( methodology, audio_methodology, quiz, visual_brief, audio, questions). Analyses that read earlier findings are placed after what they read. It only creates: nothing is priced, run or spent. Returns project; price it with quote_research_run. Assets must already be on your watchlist.

POST/api/v1/research/projects/update

update_research_project. projectId and any of: title, description, addAnalysisIds with placement (auto, new_stage or new_workflow), removeAnalysisIds, what it covers, reportOptionsOn and reportOptionsOff. The changes are made one after another: if one fails, the answer is 409 not_done with kept, the changes already made, which stay. Starts nothing.

POST/api/v1/research/projects/archive
POST/api/v1/research/projects/restore

archive_research_project and restore_research_project. { projectId }. Archiving what is archived, or restoring what is not, returns outcome: "unchanged".

Price, start and stop a run
POST/api/v1/research/runs/quote

quote_research_run. A saved project as it stands ({ projectId }); for new work, create the project first. Nothing in the project changes. Returns quote: { quoteId, priceCredits, projectId, projectTitle, covers, analyses, expiresAt, dailyLimit, startable }. startable is null, with startableUnknown saying why, when today's limit could not be read; the start checks it. A newer quote can replace an earlier unstarted one (quote_replaced), so one run never starts twice.

POST/api/v1/research/runs/start

start_research_run. { quoteId, priceCredits, clientRequestId }, where priceCredits is the price you agreed to. A run never starts above it (price_higher); if the price fell, it starts at the lower one. Returns run: { runGroupId, projectId, priceCredits, admission }; follow it with get_research_run.

POST/api/v1/research/runs/stop

stop_research_run. { projectId }. What the run found so far is kept; stopping a run does not refund the part that did not run.

Refresh connected balances
POST/api/v1/balances/refresh

refresh_connected_balances. Refreshes your balances from the exchanges you connected in AstraEye, with the keys you stored there. Free. Returns exchanges, each refreshed or failed, never an amount.

Earnings Radar and the research library

Through a connected assistant, on every plan including the free plan. turn_on_earnings_radar and turn_off_earnings_radar. { assetId }, one U.S. stock. They work exactly as the switch in Settings: turning a stock on also turns the Earnings Radar email on, and a refusal says why in the same words. Returns outcome and earningsRadar (on or off).

get_earnings_calendar. Your Earnings Radar stocks, each with the next report date AstraEye has (announced or projected), the days until it, and the Radar reports already delivered. The research figures stay in the reports.

list_public_reports. The reports in the public research library, newest first; get_research_report reads one by its id.

Done once

Every change takes an optional clientRequestId, a UUID you generate (required to start a run). Sending the same request again with the same id returns its first result instead of acting twice, for 7 days; the same id with different arguments returns 409 idempotency_conflict. A refusal changes nothing and is not kept, so the same request with the same id can be sent again once what stopped it has cleared; an answer after which part of the request stands (not_done with partial, or outcome_unknown) is kept, so a retry never does it twice. A successful action returns outcome: done, unchanged (with a message), priced or started.

Never through the API

Setting up, changing or removing a schedule is never available through the API; schedules are managed in AstraEye.

Credits
  • A run's price is held before it is launched, against this access's daily credit limit and your account's total API spending today.
  • It is charged only when the Research Lab accepts the run.
  • If the Research Lab rejects it, or it expires or is cancelled before it starts, the held credits are released. If the outcome cannot be confirmed, they stay held for that day.
  • If the price does not fit in what is left of the limit, nothing starts (daily_limit_reached).
  • Stopping a run does not refund the part that did not run: the credits it was charged stay spent.
  • For each run started this way, AstraEye sends an in-app notice and an email with what it cost, and its results arrive in your SAGE conversation when it finishes.
Rate limits
OperationShort windowDaily
List projects, reports, analyses or templates, or read one analysis or template (per token or connection)60 per 5 minutes2,000
Retrieve a report summary, methodology or test (per token / per account)40 / 60 per 5 minutes300 / 400
Send a SAGE message (per token / per account)60 / 90 per 5 minutes1,000 / 1,500
Check a SAGE turn (per token / per account)120 / 180 per 5 minutes5,000 / 8,000
Read SAGE messages (per token / per account)60 / 90 per 5 minutes2,000 / 3,000
Take an action (per token / per account)30 / 45 per 5 minutes500 / 750
Refresh connected balances (per token / per account)6 / 6 per hour48 / 48

Listing, finding assets and reading the watchlist are limited per token, or per connection for a connected assistant. Report reads (summary, methodology and test) share one allowance, and SAGE operations and actions have the ones in the table; a balance refresh counts as an action too. Both are limited per token or connection and also per account, across your token and any assistant you have connected. A request exceeding a limit returns 429 with a Retry-After header in seconds; honour that interval before retrying. Through a connected assistant, a limit comes back as an error in the tool result instead. These are the published limits referred to in Terms Section 14, and AstraEye Labs may adjust them under Section 14.1.

Error responses

Errors are returned as { "error": { "code": "…", "message": "…" } }. A failure is never represented as an empty result set.

StatusCodeCondition
401invalid_tokenThe credential is missing, malformed, unrecognized, revoked, or expired. Issue a new token in settings.
400unsupported_languageThe language parameter names a language this report is not available in. The message lists the languages that are, and the same list is on the report index as availableLanguages.
403tier_requiredThe account's plan does not include the Research API. The message names the plans that do.
403account_ineligibleThe account is not currently eligible, for example where it is suspended or a legal disclosure requires acceptance in the browser.
404not_foundThe Research API is not enabled for this account, the requested report does not belong to it, or the report has no summary, methodology or test to return.
422unavailable_for_exportThe report cannot be delivered through the API because part of it is not written prose. It is available in full on the results page in the browser.
429rate_limitedA rate limit was exceeded, or SAGE is busy for this account. Honour the Retry-After header when it is present.
503upstream_unavailableThe research service is temporarily unreachable. Retry after a short interval.
400invalid_requestThe SAGE message body is not exactly { clientMessageId, text, conversationId? }, an action's body is not as documented above, or a parameter is out of range.
400invalid_cursorThe cursor does not belong to this conversation.
402daily_limit_reachedThis access's daily credit limit, counted against your account's total API spending today, is reached or is 0. It resets at 00:00 UTC.
402insufficient_creditsThe account does not have enough Astra Credits for a SAGE reply.
403insufficient_scopeThe token was not created with the sage:chat permission.
404conversation_not_foundThe conversation does not exist or is not yours.
404turn_not_foundThe turn does not exist or is not yours.
409idempotency_conflictThis clientMessageId or clientRequestId was already used for a different message or request.
409request_in_progressA request with this clientRequestId is still being carried out. Retry it in a moment.
404unknown_assetAn assetId is not an asset research can cover. The ids are listed; look them up with find_assets.
409not_on_watchlistAn asset is not on your watchlist. Add it with add_to_watchlist first.
422refusedThe request cannot be carried out as a whole; reasons lists every reason, and nothing was done.
422nothing_to_doThe request asks for nothing to be changed.
409not_doneA step failed part way. takenBack says whether watchlist additions and a project it created were taken back; kept lists the changes that were already made and stay (partial: true). A retry with the same clientRequestId returns this answer.
503runs_unavailableWhether a run is in progress could not be read, so nothing was stopped. Try again shortly.
409project_archivedThe project is archived. Restore it with restore_research_project first.
404quote_not_foundNo quote with that id belongs to this account.
409quote_expiredThe quote expired. Get a new one.
409quote_replacedA newer quote replaced this one.
409price_higherThe quote now costs more than the priceCredits sent, so nothing started.
409already_startedThis quote's run was already started.
409price_changedThe price changed before the run was admitted, so it did not start and nothing was charged. Get a new quote.
409scope_changedWhat the project covers changed after it was priced. Get a new quote.
409preparing_contextThe project is still being prepared. Try again in a minute.
409not_startedThe run did not start, and nothing was charged.
502outcome_unknownWhether the run started, or how much of the request was done before an error, could not be confirmed. A run's credits stay held for the day until the Research Lab's record says; check the project or the watchlist before sending it again under a new clientRequestId.
502not_pricedThe run could not be priced just now.
502action_failedThe action could not be done just now. Try again.
403not_availableRefreshing connected balances is not available for this account.
503credits_unavailableThe Astra Credit balance could not be checked, so nothing was charged. Retry shortly with a new clientMessageId.
503account_unavailableThe account cannot use SAGE right now. Sign in to AstraEye to review it.
502sage_unavailableSAGE could not answer. Send the message again with a new clientMessageId.
Token lifecycle and enforcement

One token may be active per account. Issuing a replacement invalidates the previous token immediately. Tokens expire 90 days after issue, and a notice is sent in advance of expiry. Settings displays recent API activity for the account; where activity is not recognized, revoke the token there. Token creation and revocation each generate a security notification, and resetting your password or signing out of all sessions also revokes the token and ends every assistant connection. Connections are otherwise separate from the token, and each can be disconnected on its own in Settings.

AstraEye Labs may limit, suspend, or discontinue the Research API, revoke any token, and adjust rate limits and quotas, including where it reasonably believes Terms Section 14.1 has been breached or where required by a data provider's terms. Breach of Section 14.1 is a breach of the Terms of Service and may result in termination under Section 21.