> ## 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 a question

> Ask a question about a company, a person or a market and get a direct answer with a citation for every claim. Coming soon.

> [!NOTE]
>
> **Coming Soon.** Ask is not available yet, and these endpoints are not live. This page is the planned contract, published early so you can design against it. Fields can change before release. Ask is not part of the [OpenAPI specification](https://docs.data.avina.io/api-reference/openapi.md) until then.

Ask takes a question in plain language and returns a direct answer. Every factual claim in the answer carries a numbered citation, and when the evidence does not support an answer, the response says so instead of guessing.

Like a search, a question is answered in the background. `POST /ask` returns `202` with an `id`. Poll [`GET /ask/{ask_id}`](#get-an-answer) until `status` is `completed` or `failed`.

> [!WARNING]
>
> Asking a question spends credits for the research it needs, at provider cost plus the 5% platform fee. Set `max_credits` to cap it. Reading an answer is free. See [Pricing](https://docs.data.avina.io/concepts/pricing.md).

### Headers

**Idempotency-Key** `string`

A unique string for this request, 1 to 255 characters. Retrying with the same key and body returns the original response instead of asking again.

### Body

**question** `string` *required*

The question, in plain language. Ask one thing at a time for the clearest answer.

Maximum 1,000 characters.

**about** `object`

Limits the question to one company or one person. Send exactly one of the two fields. Without `about`, the question is answered from across the data network, which suits market questions.

**properties**

**company\_domain** `string`

The company's website domain, such as `northwindpay.example`.

**person\_linkedin\_url** `string`

The person's LinkedIn profile URL.

**output\_schema** `object`

A [JSON Schema](https://json-schema.org) describing the shape you want the answer in. When you send one, the response also carries `data`, an object that matches the schema. Useful when code or an AI agent will read the answer. A field the evidence cannot fill is `null`.

**max\_credits** `number`

The most credits this question may spend. 1 credit = \$1.00. When the limit is reached, research stops and the answer is written from what was found.

### Response

**`202`** The question was accepted. The same object is returned by `GET /ask/{ask_id}`.

**object** `string` *required*

Always `answer`.

**id** `string` *required*

The answer's identifier. Use it to read the answer.

**status** `string` *required*

`queued` and `running` are in progress. `completed` and `failed` are final.

**question** `string` *required*

The question as you sent it.

**about** `object | null` *required*

The company or person the question was limited to, or `null`.

**outcome** `string | null` *required*

How well the question could be answered. `null` until `status` is `completed`.

* `answered`: the evidence supports a full answer.
* `partially_answered`: part of the question could be answered. `answer` says which part could not.
* `insufficient_evidence`: no reliable answer was found. `answer` explains what was missing.

**answer** `string | null` *required*

The answer, in Markdown. Citations appear as numbered markers such as `[1]`, each matching an entry in `citations`. `null` until `status` is `completed`.

**data** `object | null` *required*

The answer in the shape of your `output_schema`. `null` when you did not send one.

**citations** `object[]` *required*

The sources the answer relies on, in the order they are first cited.

**item properties**

**number** `integer` *required*

The marker used in `answer`, starting at 1.

**url** `string | null` *required*

The source page. `null` when the source is a data record with no public page.

**title** `string` *required*

The page title, or a short description of the data record.

**quote** `string | null`

The passage that supports the claim, quoted from the source.

**published\_at** `string | null`

When the source was published, when known.

**credits\_charged** `number` *required*

Credits charged for this question so far. Final once `status` is `completed` or `failed`.

**error** `string | null` *required*

A message when `status` is `failed`.

**created\_at** `string` *required*

When the question was asked.

**completed\_at** `string | null` *required*

When the answer was finished.

**url** `string` *required*

The URL to read this answer from.

## Get an answer

`GET /ask/{ask_id}` returns the same `answer` object. Poll it every 2 seconds, slowing to every 10, until `status` is `completed` or `failed`. Reading an answer is free.

**ask\_id** `string` *required*

The answer's `id`, returned when the question was asked.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.avina.io/v1/ask/$ASK_ID \
  -H "Authorization: Bearer $AVINA_API_KEY"
```

```json 200 (completed) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "answer",
  "id": "9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04",
  "status": "completed",
  "question": "What does this company sell, and who does it sell to?",
  "about": { "company_domain": "northwindpay.example" },
  "outcome": "answered",
  "answer": "Northwind Pay sells payments infrastructure for lenders: APIs for sending loan funds and collecting repayments [1]. Its customers are mid-market consumer and small-business lenders in the US [1][2].",
  "data": null,
  "citations": [
    {
      "number": 1,
      "url": "https://northwindpay.example/product",
      "title": "Product | Northwind Pay",
      "quote": "Disburse loans and collect repayments through one API.",
      "published_at": null
    },
    {
      "number": 2,
      "url": "https://northwindpay.example/customers",
      "title": "Customers | Northwind Pay",
      "quote": "Trusted by mid-market lenders across the United States.",
      "published_at": "2026-09-14"
    }
  ],
  "credits_charged": 0.21,
  "error": null,
  "created_at": "2026-11-12T17:20:03Z",
  "completed_at": "2026-11-12T17:20:41Z",
  "url": "https://api.avina.io/v1/ask/9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04"
}
```

When the evidence is not there, the answer says so:

```json 200 (insufficient evidence, shortened) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "answer",
  "status": "completed",
  "outcome": "insufficient_evidence",
  "answer": "No public source states Northwind Pay's annual revenue. The company is privately held and has not published financial results.",
  "citations": []
}
```

### Errors

| Status | Code | When |
| - | - | - |
| `400` | `invalid_request` | The request is invalid, for example a missing `question` or both fields set in `about`. |
| `401` | `invalid_api_key` | The API key is missing, invalid or revoked. |
| `402` | `usage_limit_reached` | The workspace has no credits left. Nothing was started or charged. |
| `404` | `not_found` | No answer with that `id` in this workspace. |
| `409` | `idempotency_key_reused` | The `Idempotency-Key` was already used with a different request. |
| `429` | `rate_limited` | Too many requests. Retry after `Retry-After` seconds. |

Every error uses the same shape. See [Errors](https://docs.data.avina.io/api-reference/errors.md).

> [!NOTE]
>
> The company, answer and credit figures in these examples are illustrative.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.avina.io/v1/ask \
  -H "Authorization: Bearer $AVINA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "question": "What does this company sell, and who does it sell to?",
    "about": { "company_domain": "northwindpay.example" },
    "max_credits": 1
  }'
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import uuid
import requests

response = requests.post(
    "https://api.avina.io/v1/ask",
    headers={
        "Authorization": f"Bearer {os.environ['AVINA_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "question": "What does this company sell, and who does it sell to?",
        "about": {"company_domain": "northwindpay.example"},
        "max_credits": 1,
    },
)
response.raise_for_status()
print(response.json())
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch("https://api.avina.io/v1/ask", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    question: "What does this company sell, and who does it sell to?",
    about: { company_domain: "northwindpay.example" },
    max_credits: 1,
  }),
});
const data = await response.json();
console.log(data);
```

```json 202 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "object": "answer",
  "id": "9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04",
  "status": "queued",
  "question": "What does this company sell, and who does it sell to?",
  "about": { "company_domain": "northwindpay.example" },
  "outcome": null,
  "answer": null,
  "data": null,
  "citations": [],
  "credits_charged": 0,
  "error": null,
  "created_at": "2026-11-12T17:20:03Z",
  "completed_at": null,
  "url": "https://api.avina.io/v1/ask/9b2f6c1e-4d7a-4b0e-8f3a-2c5d1e7a9b04"
}
```


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