# Calls
Call logs, history, stats, and trends
## List calls or get stats/trends
> Retrieves paginated call logs, aggregated stats, or trends based on action parameter.\
> \
> \- No action: Returns paginated call list\
> \- \`action=stats\`: Returns call status breakdown\
> \- \`action=trends\`: Returns daily call counts over time
```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"Calls","description":"Call logs, history, stats, and trends"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}},"Page":{"name":"page","in":"query","description":"Page number for pagination (1-indexed)","schema":{"type":"integer","minimum":1,"default":1}},"Limit":{"name":"limit","in":"query","description":"Number of items per page","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}},"schemas":{"CallsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"total_pages":{"type":"integer"}}},"Call":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"from_number":{"type":"string"},"to_number":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"]},"status":{"type":"string","enum":["completed","failed","in_progress","no_answer","busy"]},"duration":{"type":"integer","description":"Call duration in seconds"},"cost":{"type":"number","format":"float","description":"Call cost in cents"},"latency_ms":{"type":"integer","description":"Connection latency in milliseconds"},"phone_number_id":{"type":"string","format":"uuid"},"endpoint_id":{"type":"string","format":"uuid","nullable":true},"recording_url":{"type":"string","format":"uri","nullable":true},"hangup_cause":{"type":"string","nullable":true},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"answered_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"CallStats":{"type":"object","properties":{"completed":{"type":"integer"},"failed":{"type":"integer"},"in_progress":{"type":"integer"},"no_answer":{"type":"integer"},"busy":{"type":"integer"}}},"CallTrends":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"completed":{"type":"integer"},"failed":{"type":"integer"},"in_progress":{"type":"integer"},"no_answer":{"type":"integer"},"busy":{"type":"integer"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/calls":{"get":{"tags":["Calls"],"summary":"List calls or get stats/trends","description":"Retrieves paginated call logs, aggregated stats, or trends based on action parameter.\n\n- No action: Returns paginated call list\n- `action=stats`: Returns call status breakdown\n- `action=trends`: Returns daily call counts over time\n","operationId":"listCalls","parameters":[{"$ref":"#/components/parameters/OrganizationId"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"},{"name":"action","in":"query","description":"Action type (stats or trends)","schema":{"type":"string","enum":["stats","trends"]}},{"name":"status","in":"query","description":"Filter by call status","schema":{"type":"string","enum":["completed","failed","in_progress","no_answer","busy"]}},{"name":"direction","in":"query","description":"Filter by call direction","schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"phone_number_id","in":"query","description":"Filter by phone number ID","schema":{"type":"string","format":"uuid"}},{"name":"start_date","in":"query","description":"Filter calls from this date (for trends)","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"Filter calls until this date (for trends)","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Calls data, stats, or trends","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CallsListResponse"},{"$ref":"#/components/schemas/CallStats"},{"$ref":"#/components/schemas/CallTrends"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
## Get call details
> Retrieves detailed call information including events and recording
```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"Calls","description":"Call logs, history, stats, and trends"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"CallId":{"name":"id","in":"path","required":true,"description":"Call UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"CallDetail":{"allOf":[{"$ref":"#/components/schemas/Call"},{"type":"object","properties":{"quality_metrics":{"type":"object","properties":{"mos":{"type":"number","format":"float","description":"Mean Opinion Score (1-5)"},"jitter_ms":{"type":"integer","description":"Jitter in milliseconds"},"packet_loss":{"type":"number","format":"float","description":"Packet loss percentage"}}},"events":{"type":"array","items":{"$ref":"#/components/schemas/CallEvent"}},"transcript":{"type":"string","nullable":true}}}]},"Call":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"from_number":{"type":"string"},"to_number":{"type":"string"},"direction":{"type":"string","enum":["inbound","outbound"]},"status":{"type":"string","enum":["completed","failed","in_progress","no_answer","busy"]},"duration":{"type":"integer","description":"Call duration in seconds"},"cost":{"type":"number","format":"float","description":"Call cost in cents"},"latency_ms":{"type":"integer","description":"Connection latency in milliseconds"},"phone_number_id":{"type":"string","format":"uuid"},"endpoint_id":{"type":"string","format":"uuid","nullable":true},"recording_url":{"type":"string","format":"uri","nullable":true},"hangup_cause":{"type":"string","nullable":true},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"answered_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"CallEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"event_data":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/calls/{id}":{"get":{"tags":["Calls"],"summary":"Get call details","description":"Retrieves detailed call information including events and recording","operationId":"getCall","parameters":[{"$ref":"#/components/parameters/CallId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"Call details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Delete call record
> Deletes the call record and associated events
```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"Calls","description":"Call logs, history, stats, and trends"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"CallId":{"name":"id","in":"path","required":true,"description":"Call UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}}},"paths":{"/calls/{id}":{"delete":{"tags":["Calls"],"summary":"Delete call record","description":"Deletes the call record and associated events","operationId":"deleteCall","parameters":[{"$ref":"#/components/parameters/CallId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"204":{"description":"Call deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.krosai.com/api-reference/reference/calls.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.