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

# Sessions SDK Reference

> SDK reference for the Sessions API, available in Node.js and Python.

## Sessions

### Create a Session

Create a thread for traces.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.sessions.create(external_id="<id>", duration=7329.24, contact_ids=[
          "<value 1>",
          "<value 2>",
      ], billing={
          "input_cost": 5975.95,
          "output_cost": 754.22,
          "total_cost": 2965.14,
      }, usage={
          "prompt_tokens": 424835,
          "completion_tokens": 793505,
          "total_tokens": 726901,
      }, traces_count=451437, tags=[
          "<value 1>",
          "<value 2>",
          "<value 3>",
      ])

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.sessions.create({
      externalId: "<id>",
      duration: 7329.24,
      contactIds: [
        "<value 1>",
        "<value 2>",
      ],
      billing: {
        inputCost: 5975.95,
        outputCost: 754.22,
        totalCost: 2965.14,
      },
      usage: {
        promptTokens: 424835,
        completionTokens: 793505,
        totalTokens: 726901,
      },
      tracesCount: 451437,
      tags: [
        "<value 1>",
        "<value 2>",
        "<value 3>",
      ],
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "external_id": str,  # required
        "duration": float,  # required
        "contact_ids": List[str],  # required
        "billing": {  # required
            "input_cost": float,  # required
            "output_cost": float,  # required
            "total_cost": float,  # required
        },
        "usage": {  # required
            "prompt_tokens": int,  # required
            "completion_tokens": int,  # required
            "total_tokens": int,  # required
        },
        "traces_count": int,  # required
        "tags": List[str],  # required
        "project_id": Optional[str],
        "started_at": str,  # optional
        "updated_at": str,  # optional
        "title": Optional[str],
        "client": Optional[str],
        "repo": Optional[str],
        "kind": Optional[Literal["THREAD_KIND_UNSPECIFIED", "THREAD_KIND_CONVERSATION", "THREAD_KIND_CODING_AGENT"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      externalId: string;  // required
      duration: number;  // required
      contactIds: string[];  // required
      billing: {  // required
        inputCost: number;  // required
        outputCost: number;  // required
        totalCost: number;  // required
      };
      usage: {  // required
        promptTokens: number;  // required
        completionTokens: number;  // required
        totalTokens: number;  // required
      };
      tracesCount: number;  // required
      tags: string[];  // required
      projectId?: string;
      startedAt?: Date;
      updatedAt?: Date;
      title?: string;
      client?: string;
      repo?: string;
      kind?: "THREAD_KIND_UNSPECIFIED" | "THREAD_KIND_CONVERSATION" | "THREAD_KIND_CODING_AGENT";
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "external_id": str,
        "duration": float,
        "contact_ids": List[str],
        "billing": {
            "input_cost": float,
            "output_cost": float,
            "total_cost": float,
        },
        "usage": {
            "prompt_tokens": int,
            "completion_tokens": int,
            "total_tokens": int,
        },
        "traces_count": int,
        "tags": List[str],
        "project_id": Optional[str],
        "started_at": str,  # optional
        "updated_at": str,  # optional
        "title": Optional[str],
        "client": Optional[str],
        "repo": Optional[str],
        "kind": Optional[Literal["THREAD_KIND_UNSPECIFIED", "THREAD_KIND_CONVERSATION", "THREAD_KIND_CODING_AGENT"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      externalId: string;
      duration: number;
      contactIds: string[];
      billing: {
        inputCost: number;
        outputCost: number;
        totalCost: number;
      };
      usage: {
        promptTokens: number;
        completionTokens: number;
        totalTokens: number;
      };
      tracesCount: number;
      tags: string[];
      projectId?: string;
      startedAt?: Date;
      updatedAt?: Date;
      title?: string;
      client?: string;
      repo?: string;
      kind?: "THREAD_KIND_UNSPECIFIED" | "THREAD_KIND_CONVERSATION" | "THREAD_KIND_CODING_AGENT";
    }
    ```
  </CodeGroup>
</Expandable>

### Get Count

Get total count of trace threads.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.sessions.get_count(filters={
          "interval": "SESSION_INTERVAL_LAST_30_MINUTES",
      })

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.sessions.getCount({
      filters: {
        interval: "SESSION_INTERVAL_LAST_30_MINUTES",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "filters": {  # required
            "interval": Literal["SESSION_INTERVAL_UNSPECIFIED", "SESSION_INTERVAL_ALL_TIME", "SESSION_INTERVAL_LAST_30_MINUTES", "SESSION_INTERVAL_LAST_1_HOUR", "SESSION_INTERVAL_LAST_6_HOURS", "SESSION_INTERVAL_LAST_24_HOURS", "SESSION_INTERVAL_LAST_3_DAYS", "SESSION_INTERVAL_LAST_7_DAYS", "SESSION_INTERVAL_LAST_14_DAYS", "SESSION_INTERVAL_LAST_1_MONTH", "SESSION_INTERVAL_LAST_3_MONTHS"],  # required
            "project_id": Optional[str],
            "tags": List[str],  # optional
            "start_date": Optional[str],
            "end_date": Optional[str],
            "client": Optional[str],
            "repo": Optional[str],
            "kind": Optional[Literal["THREAD_KIND_UNSPECIFIED", "THREAD_KIND_CONVERSATION", "THREAD_KIND_CODING_AGENT"]],
        },
        "limit": Optional[int],
        "page": Optional[int],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      filters: {  // required
        interval: "SESSION_INTERVAL_UNSPECIFIED" | "SESSION_INTERVAL_ALL_TIME" | "SESSION_INTERVAL_LAST_30_MINUTES" | "SESSION_INTERVAL_LAST_1_HOUR" | "SESSION_INTERVAL_LAST_6_HOURS" | "SESSION_INTERVAL_LAST_24_HOURS" | "SESSION_INTERVAL_LAST_3_DAYS" | "SESSION_INTERVAL_LAST_7_DAYS" | "SESSION_INTERVAL_LAST_14_DAYS" | "SESSION_INTERVAL_LAST_1_MONTH" | "SESSION_INTERVAL_LAST_3_MONTHS";  // required
        projectId?: string;
        tags?: string[];
        startDate?: string;
        endDate?: string;
        client?: string;
        repo?: string;
        kind?: "THREAD_KIND_UNSPECIFIED" | "THREAD_KIND_CONVERSATION" | "THREAD_KIND_CODING_AGENT";
      };
      limit?: number;
      page?: number;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "count": int,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      count: number;
    }
    ```
  </CodeGroup>
</Expandable>

### List Sessions

List trace threads from your workspace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.sessions.list(filters={
          "interval": "SESSION_INTERVAL_LAST_7_DAYS",
      })

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.sessions.list({
      filters: {
        interval: "SESSION_INTERVAL_LAST_7_DAYS",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "filters": {  # required
            "interval": Literal["SESSION_INTERVAL_UNSPECIFIED", "SESSION_INTERVAL_ALL_TIME", "SESSION_INTERVAL_LAST_30_MINUTES", "SESSION_INTERVAL_LAST_1_HOUR", "SESSION_INTERVAL_LAST_6_HOURS", "SESSION_INTERVAL_LAST_24_HOURS", "SESSION_INTERVAL_LAST_3_DAYS", "SESSION_INTERVAL_LAST_7_DAYS", "SESSION_INTERVAL_LAST_14_DAYS", "SESSION_INTERVAL_LAST_1_MONTH", "SESSION_INTERVAL_LAST_3_MONTHS"],  # required
            "project_id": Optional[str],
            "tags": List[str],  # optional
            "start_date": Optional[str],
            "end_date": Optional[str],
            "client": Optional[str],
            "repo": Optional[str],
            "kind": Optional[Literal["THREAD_KIND_UNSPECIFIED", "THREAD_KIND_CONVERSATION", "THREAD_KIND_CODING_AGENT"]],
        },
        "limit": Optional[int],
        "page": Optional[int],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      filters: {  // required
        interval: "SESSION_INTERVAL_UNSPECIFIED" | "SESSION_INTERVAL_ALL_TIME" | "SESSION_INTERVAL_LAST_30_MINUTES" | "SESSION_INTERVAL_LAST_1_HOUR" | "SESSION_INTERVAL_LAST_6_HOURS" | "SESSION_INTERVAL_LAST_24_HOURS" | "SESSION_INTERVAL_LAST_3_DAYS" | "SESSION_INTERVAL_LAST_7_DAYS" | "SESSION_INTERVAL_LAST_14_DAYS" | "SESSION_INTERVAL_LAST_1_MONTH" | "SESSION_INTERVAL_LAST_3_MONTHS";  // required
        projectId?: string;
        tags?: string[];
        startDate?: string;
        endDate?: string;
        client?: string;
        repo?: string;
        kind?: "THREAD_KIND_UNSPECIFIED" | "THREAD_KIND_CONVERSATION" | "THREAD_KIND_CODING_AGENT";
      };
      limit?: number;
      page?: number;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": str,
        "data": [{
            "id": str,
            "external_id": str,
            "duration": float,
            "contact_ids": List[str],
            "billing": {
                "input_cost": float,
                "output_cost": float,
                "total_cost": float,
            },
            "usage": {
                "prompt_tokens": int,
                "completion_tokens": int,
                "total_tokens": int,
            },
            "traces_count": int,
            "tags": List[str],
            "project_id": Optional[str],
            "started_at": str,  # optional
            "updated_at": str,  # optional
            "title": Optional[str],
            "client": Optional[str],
            "repo": Optional[str],
            "kind": Optional[Literal["THREAD_KIND_UNSPECIFIED", "THREAD_KIND_CONVERSATION", "THREAD_KIND_CODING_AGENT"]],
        }],
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        externalId: string;
        duration: number;
        contactIds: string[];
        billing: {
          inputCost: number;
          outputCost: number;
          totalCost: number;
        };
        usage: {
          promptTokens: number;
          completionTokens: number;
          totalTokens: number;
        };
        tracesCount: number;
        tags: string[];
        projectId?: string;
        startedAt?: Date;
        updatedAt?: Date;
        title?: string;
        client?: string;
        repo?: string;
        kind?: "THREAD_KIND_UNSPECIFIED" | "THREAD_KIND_CONVERSATION" | "THREAD_KIND_CODING_AGENT";
      }[];
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### List Tags

Retrieves all unique thread tags in the workspace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.sessions.list_tags()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.sessions.listTags();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

### Retrieve a Session

Get a trace thread.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.sessions.get(session_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.sessions.get({
      sessionId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "session_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      sessionId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "external_id": str,
        "duration": float,
        "contact_ids": List[str],
        "billing": {
            "input_cost": float,
            "output_cost": float,
            "total_cost": float,
        },
        "usage": {
            "prompt_tokens": int,
            "completion_tokens": int,
            "total_tokens": int,
        },
        "traces_count": int,
        "tags": List[str],
        "project_id": Optional[str],
        "started_at": str,  # optional
        "updated_at": str,  # optional
        "title": Optional[str],
        "client": Optional[str],
        "repo": Optional[str],
        "kind": Optional[Literal["THREAD_KIND_UNSPECIFIED", "THREAD_KIND_CONVERSATION", "THREAD_KIND_CODING_AGENT"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      externalId: string;
      duration: number;
      contactIds: string[];
      billing: {
        inputCost: number;
        outputCost: number;
        totalCost: number;
      };
      usage: {
        promptTokens: number;
        completionTokens: number;
        totalTokens: number;
      };
      tracesCount: number;
      tags: string[];
      projectId?: string;
      startedAt?: Date;
      updatedAt?: Date;
      title?: string;
      client?: string;
      repo?: string;
      kind?: "THREAD_KIND_UNSPECIFIED" | "THREAD_KIND_CONVERSATION" | "THREAD_KIND_CODING_AGENT";
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a Session

Delete a trace thread.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.sessions.delete(session_id="<id>")

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.sessions.delete({
      sessionId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "session_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      sessionId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Update a Session

Update a trace thread.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.sessions.update(session_id="<id>", tags=["customer-support"])

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.sessions.update({
      sessionId: "<id>",
      updateThreadRequest: {
        tags: ["customer-support"],
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "session_id": str,  # required
        "external_id": Optional[str],
        "duration": Optional[float],
        "contact_ids": List[str],  # optional
        "billing": {  # optional
            "input_cost": float,  # required
            "output_cost": float,  # required
            "total_cost": float,  # required
        },
        "usage": {  # optional
            "prompt_tokens": int,  # required
            "completion_tokens": int,  # required
            "total_tokens": int,  # required
        },
        "traces_count": Optional[int],
        "tags": List[str],  # optional
        "project_id": Optional[str],
        "started_at": str,  # optional
        "updated_at": str,  # optional
        "clear_contact_ids": Optional[bool],
        "clear_tags": Optional[bool],
        "title": Optional[str],
        "client": Optional[str],
        "repo": Optional[str],
        "kind": Optional[Literal["THREAD_KIND_UNSPECIFIED", "THREAD_KIND_CONVERSATION", "THREAD_KIND_CODING_AGENT"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      sessionId: string;  // required
      updateThreadRequest: {  // required
        externalId?: string;
        duration?: number;
        contactIds?: string[];
        billing?: {
          inputCost: number;  // required
          outputCost: number;  // required
          totalCost: number;  // required
        };
        usage?: {
          promptTokens: number;  // required
          completionTokens: number;  // required
          totalTokens: number;  // required
        };
        tracesCount?: number;
        tags?: string[];
        projectId?: string;
        startedAt?: Date;
        updatedAt?: Date;
        clearContactIds?: boolean;
        clearTags?: boolean;
        title?: string;
        client?: string;
        repo?: string;
        kind?: "THREAD_KIND_UNSPECIFIED" | "THREAD_KIND_CONVERSATION" | "THREAD_KIND_CODING_AGENT";
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "external_id": str,
        "duration": float,
        "contact_ids": List[str],
        "billing": {
            "input_cost": float,
            "output_cost": float,
            "total_cost": float,
        },
        "usage": {
            "prompt_tokens": int,
            "completion_tokens": int,
            "total_tokens": int,
        },
        "traces_count": int,
        "tags": List[str],
        "project_id": Optional[str],
        "started_at": str,  # optional
        "updated_at": str,  # optional
        "title": Optional[str],
        "client": Optional[str],
        "repo": Optional[str],
        "kind": Optional[Literal["THREAD_KIND_UNSPECIFIED", "THREAD_KIND_CONVERSATION", "THREAD_KIND_CODING_AGENT"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      externalId: string;
      duration: number;
      contactIds: string[];
      billing: {
        inputCost: number;
        outputCost: number;
        totalCost: number;
      };
      usage: {
        promptTokens: number;
        completionTokens: number;
        totalTokens: number;
      };
      tracesCount: number;
      tags: string[];
      projectId?: string;
      startedAt?: Date;
      updatedAt?: Date;
      title?: string;
      client?: string;
      repo?: string;
      kind?: "THREAD_KIND_UNSPECIFIED" | "THREAD_KIND_CONVERSATION" | "THREAD_KIND_CODING_AGENT";
    }
    ```
  </CodeGroup>
</Expandable>