<!-- llms.txt: https://workos.com/llms.txt -->

# AgentInstanceSession

:::code-group{title="Example AgentInstanceSession"}

```json language="curl"
{
  "object": "agent_instance_session",
  "id": "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "agent_instance_id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "status": "active",
  "expires_at": "2026-01-15T13:00:00.000Z",
  "revoked_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Get an agent instance session

Retrieves an agent instance session by ID.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/agents/sessions/agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.agents.get_session(agent_instance_session_id: "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.agents.get_session(
    agent_instance_session_id="agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Agents().GetSession(context.Background(), "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->agents()
    ->getSession(
        agentInstanceSessionId: "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.getSession("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Agents.GetSessionAsync("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .agents()
        .get_session("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "agent_instance_session",
  "id": "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "agent_instance_id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "status": "active",
  "expires_at": "2026-01-15T13:00:00.000Z",
  "revoked_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## List agent instance sessions

Lists the agent instance sessions in the current environment. Sessions are created when tokens are minted.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/agents/sessions" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.agents.list_sessions
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.agents.list_sessions()
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Agents().ListSessions(context.Background())
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->agents()->listSessions();
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.listSessions();
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Agents.ListSessionsAsync();
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .agents()
        .list_sessions()
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "agent_instance_session",
      "id": "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "agent_instance_id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "status": "active",
      "expires_at": "2026-01-15T13:00:00.000Z",
      "revoked_at": null,
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "agent_session_01HXYZ123456789ABCDEFGHIJ",
    "after": "agent_session_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

## Revoke an agent instance session

Revokes an agent instance session, invalidating its refresh token and every access token minted under it. Revocation is idempotent: revoking an already-revoked session keeps the original `revoked_at`, and revoking an already-expired session returns the session with `status: expired` and a null `revoked_at`.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/agents/sessions/agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY/revoke" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.agents.revoke_session(agent_instance_session_id: "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.agents.revoke_session(
    agent_instance_session_id="agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Agents().RevokeSession(context.Background(), "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->agents()
    ->revokeSession(
        agentInstanceSessionId: "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.revokeSession("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Agents.RevokeSessionAsync("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .agents()
        .revoke_session("agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "agent_instance_session",
  "id": "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "agent_instance_id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "status": "active",
  "expires_at": "2026-01-15T13:00:00.000Z",
  "revoked_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

### agent_instance_session

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "agent_instance_session" | Yes | Distinguishes the agent instance session object. |
| `id` | string | Yes | Unique identifier of the agent instance session. |
| `agent_instance_id` | string | Yes | The agent instance the session belongs to. |
| `status` | "active" \| "revoked" \| "expired" | Yes | Derived from `revoked_at` and `expires_at` at read time; a revoked session stays `revoked` even after it expires. |
| `expires_at` | string | Yes | Timestamp when the session expires. |
| `revoked_at` | string | No | Timestamp when the session was revoked; `null` if it has not been revoked. |
| `created_at` | string | Yes | Timestamp when the session was created. |
| `updated_at` | string | Yes | Timestamp when the session was last updated. |

### GET /agents/sessions/{agent_instance_session_id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_instance_session_id` | string | Yes | The unique ID of the agent instance session. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `agent_instance_session` | object | Distinguishes the agent instance session object. |

### GET /agents/sessions

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `before` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. |
| `after` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. |
| `limit` | integer | No | Upper limit on the number of objects to return, between `1` and `100`. Defaults to `10`. |
| `order` | "normal" \| "desc" \| "asc" | No | Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). Defaults to `normal`. |
| `agent_blueprint_id` | string | No | Only return sessions of instances minted from this blueprint. |
| `agent_instance_id` | string | No | Only return sessions belonging to this agent instance. |

### POST /agents/sessions/{agent_instance_session_id}/revoke

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_instance_session_id` | string | Yes | The unique ID of the agent instance session. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `agent_instance_session` | object | Distinguishes the agent instance session object. |