> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AlphaSense

> Search the AlphaSense research corpus and ask cited research questions from your agents.

## Overview

The AlphaSense integration gives agents read-only access to the AlphaSense
research corpus — broker and independent research, earnings call transcripts,
SEC and international filings, expert call transcripts, investor presentations,
and news.

It exposes three tools:

| Tool                | Purpose                                                                                                        | Cost             |
| ------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------- |
| `alphasense_search` | Keyword/boolean document search. Returns document metadata plus a link that opens each document in AlphaSense. | Free             |
| `alphasense_lookup` | Resolves the IDs filters need — company IDs, document-type IDs, watchlists.                                    | Free             |
| `alphasense_ask`    | GenSearch: a synthesized answer with inline, deep-linked citations.                                            | Consumes credits |

### The intended pattern

The AlphaSense API returns document **metadata only** — there is no endpoint
that returns document text. That shapes how agents should use it:

1. `alphasense_lookup` to turn a company name into an AlphaSense company ID.
2. `alphasense_search` to find relevant documents. This is free, so narrowing
   here costs nothing.
3. `alphasense_ask` with those document IDs (`document_ids`) to read into them,
   or with corpus filters to ask a broader question.

Every search result carries a `url` of the form
`https://research.alpha-sense.com/?docid=<id>`, so a user reading an agent's
answer can click straight through to the underlying document in AlphaSense.
GenSearch citations are deep-linked the same way and additionally jump to the
cited passage.

## Credits

GenSearch is metered against your AlphaSense license:

| Mode            | Credits | Typical time | Use for                               |
| --------------- | ------- | ------------ | ------------------------------------- |
| `fast`          | 10      | \~30s        | Simple factual lookups                |
| `auto`          | 10      | \~30–90s     | **Default.** Most questions           |
| `think_longer`  | 25      | \~60–90s     | Comparative or multi-company analysis |
| `deep_research` | 100     | 12–15 min    | Full research reports                 |

`alphasense_search` and `alphasense_lookup` do **not** consume credits. Because
allowances are finite, the tool descriptions steer agents toward searching first
and reserve `deep_research` for explicit user requests.

<Note>
  `deep_research` can run longer than a single tool call waits. When that happens
  the tool returns a `conversation_id` and reports that the search is still
  running — the agent calls `alphasense_ask` again with that ID (and no prompt) to
  collect the answer. The credits are spent at kickoff, so resuming is always
  cheaper than re-asking.
</Note>

## Connecting

Control Hub → Integrations → AlphaSense. Organization admins only.

Five fields are required:

| Field             | Where it comes from                                                            |
| ----------------- | ------------------------------------------------------------------------------ |
| API Key           | The credential bundle AlphaSense provides when your API license is provisioned |
| Client ID         | Same bundle — looks like `as-api-your-firm-xxxxxx-default-agent`               |
| Client Secret     | Same bundle                                                                    |
| Platform Username | Email of an AlphaSense user licensed for API access                            |
| Platform Password | That user's AlphaSense platform password                                       |

<Warning>
  **The connection acts as a named user.** AlphaSense's Agent API only supports the
  OAuth2 password grant — `client_credentials` is rejected — so the integration
  signs in as the platform user you supply. It stops working if that person leaves
  or resets their password. Use a dedicated service user if your license permits
  one.

  If the account has never been signed into, set the password first through
  AlphaSense's forgot-password email flow, then connect.
</Warning>

Connecting validates the credentials by minting a real access token and running a
test query, so a successful connect means the integration works end to end.

## Tool reference

### `alphasense_search`

Searches the corpus and returns matching documents.

* `query` — keyword expression supporting boolean logic, e.g.
  `earnings AND (margin OR pricing)`. Escaped quotes force an exact phrase match
  with smart synonyms off.
* `proximity` — maximum word distance between terms (default 15).
* `companies` / `exclude_companies` — AlphaSense company IDs (e.g. `TK760026`).
  These are **not tickers**; resolve them with `alphasense_lookup` first.
* `watchlists` — watchlist IDs.
* `date_preset` — `LAST_24_HOURS`, `LAST_7_DAYS`, `LAST_30_DAYS`, `LAST_90_DAYS`,
  `LAST_6_MONTHS`, `LAST_12_MONTHS`, `LAST_18_MONTHS`, `LAST_2_YEARS`.
* `date_from` / `date_to` — custom ISO range; overrides `date_preset`.
* `doc_type_ids` — document-type IDs from `alphasense_lookup`, e.g. `31019`
  (Broker & Independent Research), `21000` (Expert Transcript Library).
* `industries` — GICS codes. `countries` — ISO 3166-1 alpha-2, uppercase.
* `document_authors`, `expert_perspectives`, `analyst_perspectives`,
  `expert_transcript_types`.
* `limit` (1–100, default 25) and `cursor` for paging.

Returns each document's `id`, `title`, `released_at`, `type`, `page_count`,
`authors`, `companies`, and `url`, plus `total_count` and `next_cursor`.

### `alphasense_ask`

* `prompt` — the research question.
* `mode` — `fast`, `auto` (default), `think_longer`, `deep_research`.
* `document_ids` — ask within specific documents. **Mutually exclusive** with the
  corpus filters above; combining them returns a validation error.
* `use_web_search` — blend public web results with AlphaSense sources.
* `conversation_id` — with a prompt, asks a follow-up on an existing thread;
  without one, resumes waiting on an in-flight search.
* `max_wait_seconds` — how long to wait before returning a resumable ID.

Returns `answer` as markdown with inline `[[n • Source]]` citations that link to
the source documents.

### `alphasense_lookup`

* `resource` — `companies` (requires `keyword`), `source_types`, or `watchlists`.

Company resolution is inferred from how often a company is the primary subject of
documents matching the keyword, ranked best-first. It is not an authoritative
company directory, so confirm the top hit is the intended company before relying
on it.

## Limitations

* **Read-only.** Nothing in this integration writes to AlphaSense.
* **No document text.** The API exposes no content-retrieval endpoint. Use
  `alphasense_ask` with `document_ids` to read into a document, or open its `url`.
* **Document summaries are entitlement-gated** and are not returned on all
  license tiers.
* **Source filtering is by document type only.** AlphaSense's separate `sources`
  filter silently ignores the IDs it is given, so it is deliberately not exposed —
  use `doc_type_ids`.