---
title: "Get usage logs for your API keys"
method: POST
path: "/logs"
---

# Get usage logs for your API keys

`POST /logs`

## Request

- Base URL: `https://api.tavily.com`
- URL: `https://api.tavily.com/logs`
- Auth: HTTP bearer

Retrieve per-request usage logs for the API keys under your account or organization.

## Request body

- object
  - `limit` integer: Maximum number of logs to return, most recent first.
  - `start_date` string, date: Inclusive start of the log window (YYYY-MM-DD).
  - `end_date` string, date: Inclusive end of the log window (YYYY-MM-DD).
  - `endpoints` string[]: Only return logs for these endpoints. By default, logs for all endpoints are returned.
  - `project_id` string: Only return logs for a single project.
  - `filter_by_api_key` boolean: When `true`, return only logs for the API key provided in the Authorization header. When `false` (default), logs for all API keys under your account or organization are returned.

## Response `200`

Usage logs returned successfully

- object
  - `logs` object[]: Matching log entries, most recent first. Log entries never include the input or output of the original request.
    - `timestamp` string, date-time: When the request was made
    - `endpoint` 'search' | 'extract' | 'map' | 'crawl' | 'research': Which Tavily API was called
    - `depth` string: The request depth (e.g. `basic`, `advanced`). For `research` requests, the model tier.
    - `response_time` number: Server-side response time in seconds
    - `credits` number: API credits the request consumed
    - `api_key` string: The API key that made the request, masked to its last 4 characters
    - `request_id` string: Unique identifier of the original request
  - `count` integer: Number of log entries returned
  - `response_time` number: Response time of this logs request in seconds
  - `request_id` string: Unique identifier of this logs request

## Other responses

- `400`: Bad Request — invalid endpoints value or date range.
- `401`: Unauthorized - Your API key is wrong or missing.
- `403`: Forbidden — usage logs are only available to paying customers.
- `429`: Too Many Requests
- `504`: Gateway Timeout — the logs query timed out.

## Changes

- **2026-11-03** `c97103b0bfa3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/changes/logs/post.md)

---

[API](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api.md) - [All operations](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/revisions/c97103b0bfa3?raw)