Research API

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.

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.

Claude and ChatGPT can read your research and discuss it with you. 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.

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 talk to SAGE in your SAGE conversation and let SAGE act for you there as it does in the app, 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.

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.

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"

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

Returns the research projects belonging to the authenticated account, ordered newest first.

{
  "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,
      "scheduled": true
    }
  ]
}

Returns at most 100 projects per page, ordered newest first. Continue by passing nextCursor as cursor until hasMore is false.

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.

{
  "hasMore": false,
  "nextCursor": null,
  "reports": [
    { "id": "…", "researchId": "…", "generatedAt": "2026-08-24T09:31:00.000Z",
      "availableLanguages": [ "en", "ru" ] }
  ]
}

Returns at most 100 reports per page. 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.

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.

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

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.

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

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.

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

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.

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

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

{
  "report": {
    "id": "…",
    "researchId": "…",
    "generatedAt": "2026-08-24T09:31:00.000Z",
    "language": "ru",
    "availableLanguages": [ "en", "ru" ],
    "coverage": "partial",
    "summary": {
      "title": "…",
      "titleLanguage": "ru",
      "executiveSummary": "…",
      "executiveSummaryLanguage": "en",
      "sections": [ { "id": "…", "heading": "…", "body": "…", "scientistId": "…",
                      "language": "ru" } ],
      "conclusion": "…",
      "conclusionLanguage": null,
      "questions": [ { "id": "…", "question": "…", "answer": "…", "scientistId": "…",
                       "language": "ru" } ],
      "disclosures": {
        "informationalNotice": "…",
        "provenanceDisclosure": "…",
        "sources": { "notice": "…", "url": "…/data-sources", "credits": [ "…" ] },
        "notAdvice": true,
        "adviceDeclined": false
      }
    }
  }
}

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.

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.

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.

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.

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.

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 can also act for you; see the next section. When a run finishes, the result arrives in the same conversation.

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.

The state of one turn: generating, completed (with reply, and pendingAction and actions as on the reply) or failed.

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.

SAGE chat includes letting SAGE act for you, the way it does in the app.

Listing is limited per token, or per connection for a connected assistant. Report reads (summary, methodology and test) share one allowance, and SAGE operations have the ones in the table. 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.

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

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.