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

# Run Research

> Start a full research workflow and receive a session_id for async tracking.

# Run Research

## Endpoint

`POST /functions/v1/run-research`

## Purpose

Starts a full research workflow and returns a `session_id` immediately. Use `Get Session Status` to retrieve the final result.

## Authentication

Required:

`Authorization: Bearer YOUR_ACCESS_TOKEN`

## Request headers

* `Authorization`
* `Content-Type: application/json`

## Request body

### Required fields

| Field | Type | Description |
| - | - | - |
| `instructions` | `string` | The main task for the research workflow |
| `settings` | `object` | Execution settings |

### Common settings

| Field | Type | Description |
| - | - | - |
| `country_code` | `string` | Country code such as `us` |
| `search_enabled` | `boolean` | Whether search should be enabled |
| `deepsearch_model` | `string` | Model used for deep research planning |
| `finalizer_model` | `string` | Model used for final result generation |
| `extract_schema_json` | `string` | Optional JSON schema for extraction steps |

## Example request

```bash theme={null}
curl -X POST "https://api.neuralverge.ai/functions/v1/run-research" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Analyze the company and identify the main risks.",
    "settings": {
      "country_code": "us",
      "search_enabled": true,
      "deepsearch_model": "base",
      "finalizer_model": "gemini-3.0-pro"
    }
  }'
```

## Example response

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111"
}
```

## Next step

Poll:

`GET /functions/v1/get-session-status?session_id=...`

## Possible errors

* `400 Bad Request`
* `401 Unauthorized`
* `402 Payment Required`
* `500 Internal Error`


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