> ## Documentation Index > Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt > Use this file to discover all available pages before exploring further. # List conversations > Newest activity first. `q` searches titles (the first message). `waiting=approval` lists only the conversations with a request still open (an undecided approval or an unanswered question), the ones waiting for someone. A task’s own conversation (where the questions and approvals of a task you started are decided: `metadata.task_id` names it, and its title is “Task: ” and the start of its goal) is listed only while something in it waits for someone; fetch it by its id (the task’s `conversation_id`) any time. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/conversations openapi: 3.1.0 info: title: Eager API version: 1.0.0 description: >- Train AI agents like new hires: hand an agent your files and coach it, and it writes its own procedures and works in any software, even without an API. Talk to your agents one message at a time (POST /v1/agents/{agent_id}/responses): they answer from their files, procedures and your HTTP tools, and run tasks on their own cloud browser or your linked computers when an answer needs a website or a desktop app. Manage agents (versioned: save a draft, publish it), their procedures, browser and computers; follow conversations and tasks, answer approvals, and fetch history and recordings. Run tasks yourself on a session: a customer’s computer through an invite link, or a cloud browser. Test agents with evals: chat, browser and desktop test cases, run several times against your agents and judged on the answer. Every change is in the org’s audit log. servers: - url: https://guidinghand.ai description: Production - url: https://dev.guidinghand.ai description: Development (Stripe test mode) security: - bearerAuth: [] tags: - name: Agents - name: Agent files - name: Agent tools - name: Agent folders - name: Computers description: >- Computers your org links with the Eager app, and pools of them, for agents’ desktop tasks. Attach them to an agent in its `resources.computers`. - name: Phone numbers description: >- Bring your own Twilio numbers: connect the account, add its numbers, and pick the agent that answers each. Calls are answered by the agent's published version. - name: Sessions - name: Tasks - name: Webhooks - name: Audit log - name: Test cases - name: Test sets - name: Test runs - name: Start states - name: Runners - name: Responses description: >- Talk to an agent: each call is one turn of a conversation. The agent answers with its files, procedures and tools (and, with Run code, its own sandbox), asks for details with forms, and runs browser and desktop tasks when an answer needs a website or a desktop app. - name: Conversations description: >- The history of each conversation: messages, tool calls and the tasks the agent started, in order. - name: Uploads description: >- Files for conversations: attach them to a message, and download what the agent’s code made. Kept as long as their conversation. - name: Procedures description: >- An agent’s playbooks: when to use each and its steps. The agent finds and follows them; ones it writes from a first run are marked written_by: agent. - name: Categories description: The kinds of request an org’s procedures and test cases are sorted into. - name: Escalations description: >- What needs your team: an approval only the team can give or a question only it can answer, in a real conversation; a procedure run that failed; and one that worked another way, with the procedure rewritten to match (a proposed change). Test chats never escalate; evals do, without webhooks. - name: Schedules description: >- Run an agent’s procedure on a cron expression, in a time zone, with the inputs it needs. Each run is a conversation of its own with nobody in it (`channel` `schedule` in its variables): the procedure’s steps without AI run outright when it has them, else the model follows it to its end. Its record says how it ended, what the agent said last and what it cost; the team hears by webhook (`schedule.run_completed`, `schedule.run_failed`), email and Slack or Teams, as the schedule says. paths: /v1/conversations: get: tags: - Conversations summary: List conversations description: >- Newest activity first. `q` searches titles (the first message). `waiting=approval` lists only the conversations with a request still open (an undecided approval or an unanswered question), the ones waiting for someone. A task’s own conversation (where the questions and approvals of a task you started are decided: `metadata.task_id` names it, and its title is “Task: ” and the start of its goal) is listed only while something in it waits for someone; fetch it by its id (the task’s `conversation_id`) any time. operationId: listConversations parameters: - name: q in: query required: false schema: type: string maxLength: 100 - name: waiting in: query required: false description: '`approval`: only conversations with an open approval or question.' schema: type: string enum: - approval - name: source in: query required: false description: '`phone`: only phone calls; `chat`: everything but phone calls.' schema: type: string enum: - phone - chat - name: agent_id in: query required: false description: Only conversations with this agent. schema: type: string - name: object in: query required: false description: >- Only conversations the AI ontology says were about this object (an object type's or a kind's id, `device`) or property (`device.serial_number`). Conversations are tagged a few minutes after they go quiet. schema: type: string - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 - name: cursor in: query required: false description: '`next_cursor` from the previous page.' schema: type: string - name: include in: query required: false description: '`total_count` adds how many match across every page.' schema: type: string example: total_count responses: '200': description: A page of conversations. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Conversation' has_more: type: boolean next_cursor: type: - string - 'null' total_count: type: integer description: >- How many match the filters across every page. Only with `include=total_count`. components: schemas: Conversation: type: object properties: object: const: conversation id: type: string example: conv_… agent_id: type: - string - 'null' description: >- The agent it’s with. `null` for the conversation of a task run without an agent. agent_version: type: - integer - 'null' title: type: - string - 'null' metadata: type: object description: Your own values, from the first message’s `metadata`. variables: type: object additionalProperties: type: string description: >- What it knew from its start: Eager's own (the date and time where the person is, the channel, and more) and the ones passed in with its first message's `variables`. session_id: type: - string - 'null' description: >- The conversation’s cloud browser session, once its agent has run a browser task. created_at: type: string format: date-time last_item_at: type: string format: date-time status: type: string enum: - open - ended description: >- `ended` once the agent ended it with its `end_conversation` tool (sent as the `conversation.ended` webhook). An ended conversation takes no more messages: a new one is refused with 409 `conversation_ended`, and a phone call hangs up. ended_at: type: - string - 'null' format: date-time end_reason: type: - string - 'null' description: Why the agent ended it, in its words. price: description: >- What it costs at list price, and what for. Left out for the `user` role. type: object properties: total_cents: type: integer description: All of it, in US cents. replies: description: 'The agent’s replies: their tokens.' type: object properties: count: type: integer cents: type: integer input_tokens: type: integer output_tokens: type: integer tasks: description: The browser and computer tasks it started. type: object properties: count: type: integer cents: type: integer phone: description: A phone call’s minutes. type: object properties: seconds: type: integer cents: type: integer securitySchemes: bearerAuth: type: http scheme: bearer description: An org API key (`gh_live_…`) from Settings → API keys in the console. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.