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

# Start a session

> Discover projects, or resolve the latest run for one project.

Discover projects, or resolve the latest run for one project.

**MCP tool:** `start_session`. **Operation:** read. Uses the authorized connection; no project or content changes are made by this tool.

## Parameters

| Name | Type | Required | Default | Meaning and accepted values |
| - | - | - | - | - |
| `project_id` | string | No | `''` | Omit to discover accessible projects. Supply a discovered project ID to retrieve its context and latest run; check the run’s status before analysis. |

## Example call

Replace ID placeholders and example selections with values from your account. This is the `params` object for MCP `tools/call`.

```json theme={null}
{
  "name": "start_session",
  "arguments": {}
}
```

## Read the response

Without a project, `action` is `session_start` and `projects` contains the project-list response. With a project, `session_ready` includes `project_id`, `run_id`, `project`, and `runs`. A project with no runs returns `no_runs`.

### Fields to use

These selected fields explain the example and the result to preserve. Field presence depends on the response; this is not a complete response schema.

| Field | Meaning and use |
| - | - |
| `action` | session\_start asks you to choose a project; session\_ready includes a selected run; no\_runs means no usable run was selected. Check the returned run before analysis. |
| `projects.projects` | Accessible project records inside the discovery response. |
| `projects.count` | Number of projects in the full discovery response. The shortened example shows only one record. |

## Response example

Selected fields from an observed IQRush Dev response. Lists are shortened and project/run IDs are placeholders. Omitted fields remain available in the actual response.

```json theme={null}
{
  "action": "session_start",
  "projects": {
    "projects": [
      {
        "project_id": "PROJECT_ID",
        "name": "Colorescience - United States - Mineral Sun Protection",
        "status": "COMPLETED"
      }
    ],
    "count": 169
  }
}
```

Read the actual returned scope, counts, and interval levels before interpreting these fields.

## Important behavior

The selected latest run can still be in progress. Check its execution and data readiness before requesting measurements.

Check tool and payload errors before using the result. [Response handling](/developers/guides/09-responses-and-metrics) explains estimates and empty results; [errors and recovery](/developers/guides/13-errors) covers invalid requests and temporary failures.


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