# Research a question with cited sources

Create an asynchronous research task with a cited report. Takes input, model, stream and more, all optional. Served by Tavily.

Create an asynchronous research task with a cited report. Submit once with action=submit, input and model=mini or pro; streaming is disabled. Reservation covers the published maximum of 110 credits ($0.88) for mini or 250 credits ($2) for pro, at $0.008/credit. Final billing uses terminal usage.credits; missing or ambiguous consumption keeps the reservation for reconciliation. Read action=result with the returned request_id at no extra cost. Only the creating workspace may read that task.

- Tool ID: `tavily/research`
- Provider: [Tavily](/providers/tavily.md)
- Capability: [Deep research & cited answers](/tools/web-search/deep-research.md)
- Price: usage based, the maximum is shown before a run
- Authentication: an authorised Agentik workspace is required for execution, including zero-price tools.

## Pricing contract

Billed at the cost the provider reports for the call, never above $2. Your agent sees the maximum before running.


```json
{
  "model": "reported",
  "costPath": "",
  "costTerms": [
    {
      "path": "usage.credits",
      "usd": 0.008
    }
  ],
  "requireCost": true,
  "maxUsdDefault": 0.88,
  "maxUsdCap": 2,
  "headroom": 1,
  "multipliers": [
    {
      "when": {
        "field": "model",
        "equals": "pro"
      },
      "setUsd": 2
    }
  ]
}
```

### Action-specific pricing


```json
[
  {
    "field": "action",
    "equals": "result",
    "pricing": {
      "model": "per_call",
      "amountUsd": 0
    }
  }
]
```

Pricing source: [https://docs.tavily.com/documentation/api-credits](https://docs.tavily.com/documentation/api-credits). Pay as you go: $0.008 per credit. Extract 1 credit/5 successful URLs (advanced 2); Map 1 credit/10 pages (instructions 2); Crawl mapping + extraction. Research maximum 110 credits mini, 250 pro. Actual usage.credits required; documented URL/request limits bound reservations..

Price verification date: 2026-11-03.

## Complete input schema


```json
{
  "type": "object",
  "properties": {
    "input": {
      "type": "string",
      "description": "The research task or question to investigate.",
      "minLength": 1,
      "maxLength": 20000
    },
    "model": {
      "type": "string",
      "description": "The model used by the research agent. \"mini\" is optimized for targeted, efficient research and works best for narrow or well-scoped questions. \"pro\" provides comprehensive, multi-angle research and is suited for complex topics that span multiple subtopics or domains",
      "enum": [
        "mini",
        "pro"
      ]
    },
    "stream": {
      "type": "boolean",
      "const": false
    },
    "output_schema": {
      "type": "object",
      "description": "A JSON Schema object that defines the structure of the research output. When provided, the research response will be structured to match this schema, ensuring a predictable and validated output shape. Must include a 'properties' field, and may optionally include 'required' field.",
      "properties": {
        "properties": {
          "type": "object",
          "description": "An object containing property definitions. Each key is a property name, and each value is a property schema.",
          "additionalProperties": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "object",
                  "string",
                  "integer",
                  "number",
                  "array"
                ],
                "description": "The type of the property. Must be one of: object, string, integer, number, or array."
              },
              "description": {
                "type": "string",
                "description": "A description of the property."
              },
              "properties": {
                "type": "object",
                "description": "Required when type is 'object'. Recursive definition of object properties."
              },
              "items": {
                "type": "object",
                "description": "Required when type is 'array'. Defines the schema for array items."
              }
            },
            "required": [
              "type",
              "description"
            ]
          }
        },
        "required": {
          "type": "array",
          "description": "An array of property names that are required. At least one key from the properties object must be included.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "citation_format": {
      "type": "string",
      "description": "The format for citations in the research report.",
      "enum": [
        "numbered",
        "mla",
        "apa",
        "chicago"
      ]
    },
    "include_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 20,
      "description": "Soft preference for sources. The research agent prioritizes these domains, but URLs from other domains can still appear in the final report. Matching is host-based and includes subdomains (e.g., `sec.gov` matches `sec.gov` and `data.sec.gov`). Maximum 20 entries."
    },
    "exclude_domains": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "maxItems": 20,
      "description": "Hard blocklist. No URL from a listed domain or any of its subdomains appears in the response. Subdomain matching is downward only — blocking `medium.com` also blocks `blog.medium.com`, but blocking `blog.medium.com` leaves `medium.com` itself allowed. Maximum 20 entries."
    },
    "output_length": {
      "type": "string",
      "description": "Typed control over response size. Ranges are targets, not hard caps — individual responses can fall outside when the question requires it.",
      "enum": [
        "short",
        "standard",
        "long"
      ]
    },
    "action": {
      "type": "string",
      "enum": [
        "submit",
        "result"
      ],
      "default": "submit"
    },
    "request_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "^[A-Za-z0-9_-]+$"
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "action": {
            "const": "result"
          }
        },
        "required": [
          "action"
        ]
      },
      "then": {
        "type": "object",
        "properties": {
          "action": {
            "const": "result"
          },
          "request_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9_-]+$"
          }
        },
        "required": [
          "action",
          "request_id"
        ],
        "additionalProperties": false
      },
      "else": {
        "type": "object",
        "properties": {
          "input": {
            "type": "string",
            "description": "The research task or question to investigate.",
            "minLength": 1,
            "maxLength": 20000
          },
          "model": {
            "type": "string",
            "description": "The model used by the research agent. \"mini\" is optimized for targeted, efficient research and works best for narrow or well-scoped questions. \"pro\" provides comprehensive, multi-angle research and is suited for complex topics that span multiple subtopics or domains",
            "enum": [
              "mini",
              "pro"
            ],
            "default": "mini"
          },
          "stream": {
            "type": "boolean",
            "const": false,
            "default": false
          },
          "output_schema": {
            "type": "object",
            "description": "A JSON Schema object that defines the structure of the research output. When provided, the research response will be structured to match this schema, ensuring a predictable and validated output shape. Must include a 'properties' field, and may optionally include 'required' field.",
            "properties": {
              "properties": {
                "type": "object",
                "description": "An object containing property definitions. Each key is a property name, and each value is a property schema.",
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "object",
                        "string",
                        "integer",
                        "number",
                        "array"
                      ],
                      "description": "The type of the property. Must be one of: object, string, integer, number, or array."
                    },
                    "description": {
                      "type": "string",
                      "description": "A description of the property."
                    },
                    "properties": {
                      "type": "object",
                      "description": "Required when type is 'object'. Recursive definition of object properties."
                    },
                    "items": {
                      "type": "object",
                      "description": "Required when type is 'array'. Defines the schema for array items."
                    }
                  },
                  "required": [
                    "type",
                    "description"
                  ]
                }
              },
              "required": {
                "type": "array",
                "description": "An array of property names that are required. At least one key from the properties object must be included.",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "citation_format": {
            "type": "string",
            "description": "The format for citations in the research report.",
            "enum": [
              "numbered",
              "mla",
              "apa",
              "chicago"
            ],
            "default": "numbered"
          },
          "include_domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "description": "Soft preference for sources. The research agent prioritizes these domains, but URLs from other domains can still appear in the final report. Matching is host-based and includes subdomains (e.g., `sec.gov` matches `sec.gov` and `data.sec.gov`). Maximum 20 entries.",
            "default": []
          },
          "exclude_domains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "description": "Hard blocklist. No URL from a listed domain or any of its subdomains appears in the response. Subdomain matching is downward only — blocking `medium.com` also blocks `blog.medium.com`, but blocking `blog.medium.com` leaves `medium.com` itself allowed. Maximum 20 entries.",
            "default": []
          },
          "output_length": {
            "type": "string",
            "description": "Typed control over response size. Ranges are targets, not hard caps — individual responses can fall outside when the question requires it.",
            "enum": [
              "short",
              "standard",
              "long"
            ],
            "default": "standard"
          },
          "action": {
            "const": "submit"
          }
        },
        "required": [
          "input"
        ],
        "additionalProperties": false
      }
    }
  ],
  "additionalProperties": false
}
```

## Published example

This is the provider tool’s published example. Replace example values with the user’s requested inputs, respecting the schema; do not execute an example merely to test a connection.


```json
{
  "tool_id": "tavily/research",
  "input": {
    "input": "Compare the public documentation of OpenAlex and Crossref for literature research.",
    "model": "mini"
  }
}
```

## Execute and retrieve

Inspect again before execution, explain the price and obtain the required authority. Use MCP run_tool or POST /v1/run with this tool ID, valid input and an idempotency key. Save the returned run ID and follow the actual state. If Agentik answers that the tool is temporarily unavailable, do not retry it blindly; use discovery to propose an alternative.

This tool uses deferred settlement. Follow its returned task/run instructions; preserve the existing reservation until the result is reconciled.

A partial or uncertain result can still have consumed provider resources. Consult [billing](/docs/billing.md), [idempotency](/docs/idempotency.md) and [asynchronous results](/docs/async.md).

[Provider documentation](https://docs.tavily.com/documentation/api-reference/endpoint/research)

[REST inspection](https://api.agentik.cc/v1/tools/tavily/research) · [OpenAPI](/openapi.json) · [Connection guide](/connect.md)

---

[HTML page](/providers/tavily/research) · [Agent index](/llms.txt)