# Mark agent read

`POST /v1/projects/{project}/agents/{agent}/mark-read`, operation `agents.MarkAgentRead`

Marks an agent read by the caller, through an event of its transcript, and returns it.

It's marked read only if the caller read through its last event, so that what came since stays unread. An agent the caller doesn't follow stays as it is. Service accounts follow no agents, and are refused.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `project` | path | Yes | `string` | The project's ID. |
| `agent` | path | Yes | `string` | The agent's ID. |

## Request body

Content-Type: `application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sequence` | `integer (int64)` | Yes | The sequence of the last event of the transcript that the caller read, such as the agent's lastSequence as they saw it. The agent is marked read only if nothing came after it, so that what it wrote since stays unread. |

## Responses

### 200

OK

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activityTime` | `string (date-time)` | Yes | When the agent was last active, as people see it, which lists order agents by: when it was created, someone wrote to it or answered it, or it stopped, as it finished its turn, asked a question, was interrupted or failed. Unlike updateTime, the steps of a turn leave it. |
| `awaitingCalls` | `string[]` | Yes | The tool calls that the agent waits for answers to, in AWAITING_INPUT. |
| `config` | `AgentConfig` | Yes | How the agent works. Set when the agent is created, then changed only by configChange events. |
| `config.environment` | `AgentEnvironmentConfig` | No | The environment the agent runs commands in, with exec, which its first command makes and each starts as it needs to; absent when nothing is set. |
| `config.instructions` | `string` | Yes | Instructions the agent follows, on top of kosem's own. |
| `config.maxModelCalls` | `integer (int32)` | Yes | The most times the agent calls its model after someone last wrote to it, before it pauses as CALL_LIMIT_REACHED until someone writes again. The agents.maxModelCalls policy lowers it where it allows fewer, for running agents too. |
| `config.model` | `string` | Yes | The alias of a model shared with the agent's project, such as claude. |
| `config.reasoningEffort` | `string` | Yes | How much the model reasons before it answers; empty for the model's default. A level the model lacks becomes the nearest it has. Values: "", `NONE`, `MINIMAL`, `LOW`, `MEDIUM`, `HIGH`, `XHIGH`, `MAX`. |
| `config.tools` | `string[]` | Yes | The tools the agent may use, by ID, such as web_search. A tool that the agents.allowedTools policy no longer allows is not offered, with a warning in the transcript. |
| `createTime` | `string (date-time)` | Yes | When the agent was created. |
| `creator` | `string` | Yes | Who created the agent, such as user:usr_…. |
| `environment` | `AgentEnvironment` | No | The agent's environment, which its first command makes; absent while it has none. |
| `environment.diskGib` | `integer (int32)` | Yes | Its disk's size, in GiB. |
| `environment.environment` | `string` | Yes | The environment's resource name, by which people who may stop or delete a project's environments do so through the environments API. |
| `environment.memoryMib` | `integer (int32)` | Yes | Its memory, in MiB. |
| `environment.state` | `string` | Yes | Where it is in its lifecycle. Values: `PROVISIONING`, `RUNNING`, `STOPPING`, `STOPPED`, `STARTING`, `DELETING`. |
| `environment.stateReason` | `string` | Yes | What it waits for, such as capacity, when it waits. |
| `environment.updateTime` | `string (date-time)` | Yes | When it last changed. |
| `environment.vcpus` | `integer (int32)` | Yes | Its virtual CPUs. |
| `jobs` | `AgentJob[]` | Yes | The background jobs that the agent left running and is told the end of, while its environment runs. As each ends, it starts a turn of an IDLE agent, unless someone interrupted its last turn, so an agent that finished its turn with jobs goes on when they end. |
| `lastSequence` | `integer (int64)` | Yes | The sequence of the transcript's last event. |
| `lastStop` | `AgentStop` | No | Why the agent last stopped; absent until it first does. |
| `lastStop.message` | `string` | Yes | What happened, for people, when it did not simply finish. |
| `lastStop.reason` | `string` | Yes | Why it stopped: END_TURN, it finished its turn; INTERRUPTED, someone interrupted it; LIMIT_REACHED, a limit of billing, a spend limit or a quota stopped it, and writing to it goes on only once the limit allows; CALL_LIMIT_REACHED, it called its model as many times as it can since someone last wrote to it, and writing to it lets it go on; ERROR, something failed, such as the model being unavailable. Values: `END_TURN`, `INTERRUPTED`, `LIMIT_REACHED`, `CALL_LIMIT_REACHED`, `ERROR`. |
| `name` | `string` | Yes | Resource name, projects/{project_id}/agents/{agent_id}. |
| `state` | `string` | Yes | What the agent is doing: IDLE with nothing to do, as lastStop says, until a message starts it again; QUEUED with work it starts on shortly; RUNNING; or AWAITING_INPUT, waiting for answers to the tool calls in awaitingCalls, such as a question it asked. Values: `IDLE`, `QUEUED`, `RUNNING`, `AWAITING_INPUT`. |
| `title` | `string` | Yes | A title for people, at most 200 characters. Empty until the agent writes one after its first answer, unless someone set it. |
| `unread` | `boolean` | Yes | Whether the agent stopped since the caller last read it: it finished its turn, failed or reached a limit, and is IDLE. Only for agents the caller follows, as people follow those they created, sent to or marked unread; always false for service accounts. MarkAgentRead marks it read. |
| `updateTime` | `string (date-time)` | Yes | When the agent last changed, or had an event. |
| `usage` | `AgentUsage` | Yes | What the agent used, all told. |
| `usage.webSearches` | `integer (int64)` | Yes | The web searches the search service answered. |
| `visibility` | `string` | Yes | Who sees the agent: PROJECT, everyone who may see the project's agents, by their roles on it; PRIVATE, its owner, those it is shared with through its IAM policy, and those who hold agents.agents.accessPrivate on the project. Values: `PROJECT`, `PRIVATE`. |

### default

Error

Base URL: `https://api.kosem.ai`. See [API conventions](https://docs.kosem.ai/reference/api-conventions.md) for authentication, pagination and errors, and [https://docs.kosem.ai/openapi.yaml](https://docs.kosem.ai/openapi.yaml) for the full OpenAPI document.