# List Chats

`GET /v1/chats`

List chats, newest first.

Authenticate with `Authorization: Bearer $TALQING_API_KEY`. Errors use the shared envelope: https://docs.talqing.com/api-reference/errors.md

## OpenAPI

```json
{
 "openapi":"3.1.0",
 "servers":[
  {
   "description":"Talqing API",
   "url":"https://api.talqing.com"
  }
 ],
 "paths":{
  "/v1/chats":{
   "get":{
    "description":"List chats, newest first.",
    "operationId":"chats.list",
    "parameters":[
     {
      "in":"query",
      "name":"limit",
      "required":false,
      "schema":{
       "default":100,
       "maximum":200,
       "minimum":1,
       "title":"Limit",
       "type":"integer"
      }
     },
     {
      "in":"query",
      "name":"offset",
      "required":false,
      "schema":{
       "default":0,
       "minimum":0,
       "title":"Offset",
       "type":"integer"
      }
     },
     {
      "in":"query",
      "name":"agent_id",
      "required":false,
      "schema":{
       "anyOf":[
        {
         "format":"uuid",
         "type":"string"
        },
        {
         "type":"null"
        }
       ],
       "title":"Agent Id"
      }
     },
     {
      "in":"query",
      "name":"contact_key",
      "required":false,
      "schema":{
       "anyOf":[
        {
         "type":"string"
        },
        {
         "type":"null"
        }
       ],
       "title":"Contact Key"
      }
     },
     {
      "in":"query",
      "name":"status",
      "required":false,
      "schema":{
       "default":"all",
       "enum":[
        "open",
        "ended",
        "all"
       ],
       "title":"Status",
       "type":"string"
      }
     },
     {
      "description":"`key:value` pairs, all must match.",
      "in":"query",
      "name":"metadata",
      "required":false,
      "schema":{
       "default":[],
       "description":"`key:value` pairs, all must match.",
       "items":{
        "type":"string"
       },
       "title":"Metadata",
       "type":"array"
      }
     }
    ],
    "responses":{
     "200":{
      "content":{
       "application/json":{
        "schema":{
         "$ref":"#/components/schemas/PageChatResponse"
        }
       }
      },
      "description":"Successful Response"
     },
     "401":{
      "$ref":"#/components/responses/Unauthorized"
     },
     "422":{
      "$ref":"#/components/responses/ValidationFailed"
     },
     "default":{
      "$ref":"#/components/responses/Error"
     }
    },
    "security":[
     {
      "BearerAuth":[]
     },
     {
      "SessionCookie":[]
     }
    ],
    "summary":"List Chats",
    "tags":[
     "chats"
    ]
   }
  }
 },
 "components":{
  "responses":{
   "Error":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"Unexpected error. Every error this API returns carries this body."
   },
   "Unauthorized":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"Missing credential, or one that is revoked or no longer a member of this organization."
   },
   "ValidationFailed":{
    "content":{
     "application/json":{
      "schema":{
       "$ref":"#/components/schemas/ErrorResponse"
      }
     }
    },
    "description":"The request did not match this operation's schema; `detail.errors` lists each field."
   }
  },
  "schemas":{
   "AgentMetadata":{
    "properties":{
     "agent_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Agent Id"
     },
     "channel":{
      "title":"Channel",
      "type":"string"
     },
     "name":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Name"
     }
    },
    "required":[
     "channel"
    ],
    "title":"AgentMetadata",
    "type":"object"
   },
   "AnalysisResponse":{
    "description":"The analysis of one call, as every reader sees it.\n\nShared verbatim by the calls API and the `session.completed` webhook so an\nintegration that reads one can read the other.",
    "properties":{
     "fields":{
      "additionalProperties":true,
      "title":"Fields",
      "type":"object"
     },
     "outcome":{
      "anyOf":[
       {
        "enum":[
         "success",
         "failure",
         "unknown"
        ],
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Outcome"
     },
     "outcome_rationale":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Outcome Rationale"
     },
     "skip_reason":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Skip Reason"
     },
     "status":{
      "default":"none",
      "enum":[
       "none",
       "pending",
       "completed",
       "failed",
       "skipped"
      ],
      "title":"Status",
      "type":"string"
     },
     "summary":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Summary"
     }
    },
    "required":[
     "status",
     "skip_reason",
     "summary",
     "outcome",
     "outcome_rationale",
     "fields"
    ],
    "title":"AnalysisResponse",
    "type":"object"
   },
   "ChatResponse":{
    "description":"One chat: a text session from its first message to its end.",
    "properties":{
     "agent":{
      "$ref":"#/components/schemas/AgentMetadata"
     },
     "analysis":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/AnalysisResponse"
       },
       {
        "type":"null"
       }
      ]
     },
     "close_reason":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Close Reason"
     },
     "contact_key":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Contact Key"
     },
     "conversation_id":{
      "anyOf":[
       {
        "format":"uuid",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Conversation Id"
     },
     "cost":{
      "anyOf":[
       {
        "$ref":"#/components/schemas/CostResponse"
       },
       {
        "type":"null"
       }
      ]
     },
     "created_at":{
      "format":"date-time",
      "title":"Created At",
      "type":"string"
     },
     "ended_at":{
      "anyOf":[
       {
        "format":"date-time",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Ended At"
     },
     "id":{
      "format":"uuid",
      "title":"Id",
      "type":"string"
     },
     "metadata":{
      "additionalProperties":{
       "type":"string"
      },
      "description":"Your own labels for this session, set by your inbound webhook.",
      "title":"Metadata",
      "type":"object"
     },
     "started_at":{
      "anyOf":[
       {
        "format":"date-time",
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "title":"Started At"
     },
     "status":{
      "enum":[
       "open",
       "ended"
      ],
      "title":"Status",
      "type":"string"
     },
     "userdata":{
      "additionalProperties":true,
      "title":"Userdata",
      "type":"object"
     }
    },
    "required":[
     "id",
     "conversation_id",
     "contact_key",
     "agent",
     "status",
     "close_reason",
     "created_at",
     "started_at",
     "ended_at",
     "cost",
     "analysis",
     "userdata",
     "metadata"
    ],
    "title":"ChatResponse",
    "type":"object"
   },
   "CostResponse":{
    "properties":{
     "duration_s":{
      "anyOf":[
       {
        "type":"integer"
       },
       {
        "type":"null"
       }
      ],
      "title":"Duration S"
     },
     "platform_fee":{
      "title":"Platform Fee",
      "type":"number"
     },
     "provider_cost":{
      "title":"Provider Cost",
      "type":"number"
     },
     "total_charge":{
      "title":"Total Charge",
      "type":"number"
     }
    },
    "required":[
     "provider_cost",
     "platform_fee",
     "total_charge"
    ],
    "title":"CostResponse",
    "type":"object"
   },
   "ErrorBody":{
    "description":"The structured half of our error contract: a human `message` plus a list\nof individual `errors` (used wherever we surface many problems at once,\nincluding tool publish, op-tree checks, and request validation). The global\nexception handlers normalize every API error to\n`{detail: {message, errors, code}}`, so SDKs can parse one shape consistently.",
    "properties":{
     "code":{
      "anyOf":[
       {
        "type":"string"
       },
       {
        "type":"null"
       }
      ],
      "default":null,
      "description":"A stable identifier for this error, when it has one.",
      "title":"Code"
     },
     "errors":{
      "items":{
       "type":"string"
      },
      "title":"Errors",
      "type":"array"
     },
     "message":{
      "title":"Message",
      "type":"string"
     }
    },
    "required":[
     "message",
     "errors"
    ],
    "title":"ErrorBody",
    "type":"object"
   },
   "ErrorResponse":{
    "description":"The body of every error response, at every status code.",
    "properties":{
     "detail":{
      "$ref":"#/components/schemas/ErrorBody"
     }
    },
    "required":[
     "detail"
    ],
    "title":"ErrorResponse",
    "type":"object"
   },
   "PageChatResponse":{
    "properties":{
     "has_more":{
      "title":"Has More",
      "type":"boolean"
     },
     "items":{
      "items":{
       "$ref":"#/components/schemas/ChatResponse"
      },
      "title":"Items",
      "type":"array"
     },
     "limit":{
      "title":"Limit",
      "type":"integer"
     },
     "offset":{
      "title":"Offset",
      "type":"integer"
     }
    },
    "required":[
     "items",
     "has_more",
     "limit",
     "offset"
    ],
    "title":"Page[ChatResponse]",
    "type":"object"
   }
  }
 }
}
```