---
title: "Sessions"
description: "API reference for creating and managing Jules sessions"
---


Sessions are the core resource in the Jules REST API. A session represents a unit of work where Jules executes a coding task on your repository.

## Create a Session

<ApiEndpoint method="POST" path="/v1alpha/sessions" description="Creates a new session to start a coding task.">

### Request Body

### Example Request

```bash
curl -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add comprehensive unit tests for the authentication module",
    "title": "Add auth tests",
    "sourceContext": {
      "source": "sources/github-myorg-myrepo",
      "githubRepoContext": {
        "startingBranch": "main"
      }
    },
    "requirePlanApproval": true
  }' \
  https://jules.googleapis.com/v1alpha/sessions
```

### Response

Returns the created [Session](/docs/api/reference/types#session) object:

```json
{
  "name": "sessions/1234567",
  "id": "abc123",
  "prompt": "Add comprehensive unit tests for the authentication module",
  "title": "Add auth tests",
  "state": "QUEUED",
  "url": "https://jules.google.com/session/abc123",
  "createTime": "2024-01-15T10:30:00Z",
  "updateTime": "2024-01-15T10:30:00Z"
}
```

</ApiEndpoint>

## List Sessions

<ApiEndpoint method="GET" path="/v1alpha/sessions" description="Lists all sessions for the authenticated user.">

### Query Parameters

### Example Request

```bash
curl -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=10"
```

### Response

```json
{
  "sessions": [
    {
      "name": "sessions/1234567",
      "id": "abc123",
      "title": "Add auth tests",
      "state": "COMPLETED",
      "createTime": "2024-01-15T10:30:00Z",
      "updateTime": "2024-01-15T11:45:00Z"
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjEwfQ=="
}
```

</ApiEndpoint>

## Get a Session

<ApiEndpoint method="GET" path="/v1alpha/sessions/{sessionId}" description="Retrieves a single session by ID.">

### Path Parameters

### Example Request

```bash
curl -H "x-goog-api-key: $JULES_API_KEY" \
  https://jules.googleapis.com/v1alpha/sessions/1234567
```

### Response

Returns the full [Session](/docs/api/reference/types#session) object including outputs if the session has completed:

```json
{
  "name": "sessions/1234567",
  "id": "abc123",
  "prompt": "Add comprehensive unit tests for the authentication module",
  "title": "Add auth tests",
  "state": "COMPLETED",
  "url": "https://jules.google.com/session/abc123",
  "createTime": "2024-01-15T10:30:00Z",
  "updateTime": "2024-01-15T11:45:00Z",
  "outputs": [
    {
      "pullRequest": {
        "url": "https://github.com/myorg/myrepo/pull/42",
        "title": "Add auth tests",
        "description": "Added unit tests for authentication module"
      }
    }
  ]
}
```

</ApiEndpoint>

## Delete a Session

<ApiEndpoint method="DELETE" path="/v1alpha/sessions/{sessionId}" description="Deletes a session.">

### Path Parameters

### Example Request

```bash
curl -X DELETE \
  -H "x-goog-api-key: $JULES_API_KEY" \
  https://jules.googleapis.com/v1alpha/sessions/1234567
```

### Response

Returns an empty response on success.

</ApiEndpoint>

## Send a Message

<ApiEndpoint method="POST" path="/v1alpha/sessions/{sessionId}:sendMessage" description="Sends a message from the user to an active session.">

Use this endpoint to provide feedback, answer questions, or give additional instructions to Jules during an active session.

### Path Parameters

### Request Body

### Example Request

```bash
curl -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Please also add integration tests for the login flow"
  }' \
  https://jules.googleapis.com/v1alpha/sessions/1234567:sendMessage
```

### Response

Returns an empty [SendMessageResponse](/docs/api/reference/types#sendmessageresponse) on success.

</ApiEndpoint>

## Approve a Plan

<ApiEndpoint method="POST" path="/v1alpha/sessions/{sessionId}:approvePlan" description="Approves a pending plan in a session.">

<ApiNote>
  This endpoint is only needed when `requirePlanApproval` was set to `true` when creating the session.
</ApiNote>

### Path Parameters

### Example Request

```bash
curl -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://jules.googleapis.com/v1alpha/sessions/1234567:approvePlan
```

### Response

Returns an empty [ApprovePlanResponse](/docs/api/reference/types#approveplanresponse) on success.

</ApiEndpoint>

## Session States

Sessions progress through the following states:

| State | Description |
|-------|-------------|
| `QUEUED` | Session is waiting to be processed |
| `PLANNING` | Jules is analyzing the task and creating a plan |
| `AWAITING_PLAN_APPROVAL` | Plan is ready and waiting for user approval |
| `AWAITING_USER_FEEDBACK` | Jules needs additional input from the user |
| `IN_PROGRESS` | Jules is actively working on the task |
| `PAUSED` | Session is paused |
| `COMPLETED` | Task completed successfully |
| `FAILED` | Task failed to complete |