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

# Ask

> Ask a question about a company, a person or a market and get a direct answer with citations.

> [!NOTE]
>
> **Coming Soon.** Ask is not available yet. This page describes how it is planned to work, so you can design for it. Details can change before release. To hear when it ships, email [support@avina.io](mailto:support@avina.io).

Search returns a list of companies or people. Ask is for when you want an answer to a question instead.

Ask takes a question in plain language and returns a direct answer, with a numbered citation for every factual claim.

## What it is for

> [card] Research an account
>
> "What does Northwind Pay sell, and who are its main competitors?"

> [card] Prepare for a call
>
> "What has this company announced in the last 90 days?"

> [card] Size a segment
>
> "Which US states have the most privately held dental groups with more than ten locations?"

> [card] Give an agent sources
>
> One tool that answers B2B questions with sources the agent can quote.

## How it will work

**1. Ask a question**

Send one question in plain language to `POST /ask`. Add `about` to limit it to one company or one person, or leave it out for a question about a market.

**2. Avina researches it**

The question is answered in the background, the same way a search runs. You get an `id` back immediately and poll for the result.

**3. Read the answer and its sources**

The answer comes back as text with numbered markers such as `[1]`. Each marker points to a source in `citations`, with the passage that supports the claim.

```json Planned request theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "question": "What does this company sell, and who does it sell to?",
  "about": { "company_domain": "northwindpay.example" },
  "max_credits": 1
}
```

```json Planned response (shortened) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "answer",
  "status": "completed",
  "outcome": "answered",
  "answer": "Northwind Pay sells payments infrastructure for lenders: APIs for sending loan funds and collecting repayments [1]. Its customers are mid-market lenders in the US [1][2].",
  "citations": [
    { "number": 1, "url": "https://northwindpay.example/product", "quote": "Disburse loans and collect repayments through one API." },
    { "number": 2, "url": "https://northwindpay.example/customers", "quote": "Trusted by mid-market lenders across the United States." }
  ],
  "credits_charged": 0.21
}
```

The full planned contract is in the [Ask reference](https://docs.data.avina.io/api-reference/ask.md).

## What you can rely on

* **Every claim is cited.** Each factual statement in an answer points to a source you can open.
* **It says when it does not know.** `outcome` is `answered`, `partially_answered` or `insufficient_evidence`. When the evidence is missing, the answer explains what could not be found instead of guessing.
* **Answers code can read.** Send an `output_schema` and the answer also comes back as an object in that shape, for your code or an AI agent to use.
* **A spend limit.** `max_credits` caps what one question can cost, in the same credits as search.

## Until it ships

Search already answers some of these questions for lists of companies:

* To answer "which companies do X?", run a [company search](https://docs.data.avina.io/capabilities/companies.md) with X as a criterion. Every result cites its evidence.
* To check one fact across many companies, add it to `criteria` and read `matched_criteria` on each result.

> [card] [Evidence and verdicts](https://docs.data.avina.io/concepts/evidence.md)
>
> How search results cite their sources today.

> [card] [Changelog](https://docs.data.avina.io/changelog.md)
>
> Release announcements.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.