# Stop

Stop the turn an agent is running on a conversation. The agent ends its current work and the conversation stays open for a follow-up.





Asks the agent to stop the turn it is running on a conversation. Use it when a task is going the wrong way or has run for too long.

```http
POST /api/public/v1/conversations/{job_id}/stop
```

No request body. Requires an API key with the `conversations:write` scope.

## What happens [#what-happens]

1. Every user message still waiting on this conversation is ended, and the agent is told to stop.
2. The response is `202 Accepted` right away. The stop itself is asynchronous.
3. When the agent confirms, a `system` message is added to the conversation: `Stopped by API key <name>. Send a message to continue.` The name is the API key's name from the dashboard.
4. If the agent has not confirmed within a minute, a `system` message says so. The agent may be offline or running an older `nairid`.

The conversation is not closed. Send a follow-up with [Continue](/api/conversations/continue) to carry on from where it stopped.

## Example [#example]

<Tabs items="[&#x22;bash&#x22;, &#x22;TypeScript&#x22;, &#x22;Ruby&#x22;, &#x22;Python&#x22;, &#x22;Go&#x22;]">
  <Tab value="bash">
    ```bash
    curl -X POST https://api.nairi.ai/api/public/v1/conversations/JOB_ID/stop \
      -H "Authorization: Bearer $NAIRI_API_KEY"
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const res = await fetch(
      `https://api.nairi.ai/api/public/v1/conversations/${jobId}/stop`,
      {
        method: "POST",
        headers: { Authorization: `Bearer ${process.env.NAIRI_API_KEY}` },
      },
    );
    const data = (await res.json()) as { job_id: string };
    ```
  </Tab>

  <Tab value="Ruby">
    ```ruby
    require "net/http"
    require "json"
    require "uri"

    uri = URI("https://api.nairi.ai/api/public/v1/conversations/#{job_id}/stop")
    req = Net::HTTP::Post.new(uri)
    req["Authorization"] = "Bearer #{ENV['NAIRI_API_KEY']}"

    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    data = JSON.parse(res.body)
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import os
    import requests

    res = requests.post(
        f"https://api.nairi.ai/api/public/v1/conversations/{job_id}/stop",
        headers={"Authorization": f"Bearer {os.environ['NAIRI_API_KEY']}"},
    )
    data = res.json()
    ```
  </Tab>

  <Tab value="Go">
    ```go
    package main

    import (
    	"encoding/json"
    	"fmt"
    	"io"
    	"net/http"
    	"os"
    )

    func main() {
    	jobID := os.Getenv("JOB_ID")
    	req, _ := http.NewRequest(
    		"POST",
    		"https://api.nairi.ai/api/public/v1/conversations/"+jobID+"/stop",
    		nil,
    	)
    	req.Header.Set("Authorization", "Bearer "+os.Getenv("NAIRI_API_KEY"))
    	res, _ := http.DefaultClient.Do(req)
    	defer res.Body.Close()
    	raw, _ := io.ReadAll(res.Body)
    	var data map[string]any
    	json.Unmarshal(raw, &data)
    	fmt.Println(data)
    }
    ```
  </Tab>
</Tabs>

## Response: `202 Accepted` [#response-202-accepted]

```json
{
  "job_id": "job_01KRK1V46BXS73CSNK2VR35NPJ"
}
```

## Errors [#errors]

| Status | Body                                                             | When                                                                                                                                                |
| ------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `404`  | `{"error":"job not found"}`                                      | The `job_id` does not exist in your organization.                                                                                                   |
| `400`  | `{"error":"job is not an API job"}`                              | The conversation was started from Slack, Discord or the dashboard. Only conversations started with `POST /conversations/start` can be stopped here. |
| `409`  | `{"error":"nothing is running for this conversation"}`           | The agent is not working on anything right now, or no agent holds the conversation.                                                                 |
| `409`  | `{"error":"a stop for this conversation is already on its way"}` | A stop was requested less than a minute ago and the agent has not answered it yet.                                                                  |
| `403`  |                                                                  | The API key does not have the `conversations:write` scope.                                                                                          |