Get organization usage across all API keys
curl --request POST \
--url https://api.tavily.com/org-usage \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"organization_name": "Acme Inc",
"start_date": "2026-05-01",
"end_date": "2026-05-27",
"project_id": "<string>",
"depth": "advanced"
}
'import requests
url = "https://api.tavily.com/org-usage"
payload = {
"organization_name": "Acme Inc",
"start_date": "2026-05-01",
"end_date": "2026-05-27",
"project_id": "<string>",
"depth": "advanced"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
organization_name: 'Acme Inc',
start_date: '2026-05-01',
end_date: '2026-05-27',
project_id: '<string>',
depth: 'advanced'
})
};
fetch('https://api.tavily.com/org-usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tavily.com/org-usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'organization_name' => 'Acme Inc',
'start_date' => '2026-05-01',
'end_date' => '2026-05-27',
'project_id' => '<string>',
'depth' => 'advanced'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tavily.com/org-usage"
payload := strings.NewReader("{\n \"organization_name\": \"Acme Inc\",\n \"start_date\": \"2026-05-01\",\n \"end_date\": \"2026-05-27\",\n \"project_id\": \"<string>\",\n \"depth\": \"advanced\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tavily.com/org-usage")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"organization_name\": \"Acme Inc\",\n \"start_date\": \"2026-05-01\",\n \"end_date\": \"2026-05-27\",\n \"project_id\": \"<string>\",\n \"depth\": \"advanced\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tavily.com/org-usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"organization_name\": \"Acme Inc\",\n \"start_date\": \"2026-05-01\",\n \"end_date\": \"2026-05-27\",\n \"project_id\": \"<string>\",\n \"depth\": \"advanced\"\n}"
response = http.request(request)
puts response.read_body{
"organization": {
"name": "Acme Inc",
"filters": {
"start_date": "2026-05-01",
"end_date": "2026-05-27",
"project_id": null,
"depth": null
}
},
"totals": {
"usage": 1820,
"paygo_cost_usd": 12.71,
"request_count": 1760,
"by_type": {
"search": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"crawl": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"extract": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"map": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"research": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
}
}
},
"keys": [
{
"key": "...AB3xQ",
"name": "production-key",
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528,
"by_type": {
"search": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"crawl": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"extract": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"map": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"research": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
}
}
}
]
}{
"detail": {
"error": "Invalid start_date; expected format YYYY-MM-DD."
}
}{
"detail": {
"error": "Unauthorized: missing or invalid API key."
}
}{
"detail": {
"error": "Please authenticate with the organization owner's personal API key, not an organization API key."
}
}{
"detail": {
"error": "Organization not found or access denied."
}
}{
"detail": {
"error": "organization_name is required."
}
}{
"detail": {
"error": "Your request has been blocked due to excessive requests. Please reduce the rate of requests."
}
}{
"detail": {
"error": "Internal server error"
}
}{
"detail": {
"error": "Request timed out while fetching usage. Please try again or contact our team at support@tavily.com."
}
}Enterprise Endpoints
Organization Usage
Retrieve usage (credits), pay-as-you-go USD cost, and request counts for every API key under an organization you own, mirroring the platform’s Usage analytics page.
Identify the organization by name in the request body. Authenticate with the organization owner’s personal API key — the key from the owner’s own personal account, not an organization or enterprise API key. Supports date-range, project, and depth filtering.
POST
/
org-usage
Get organization usage across all API keys
curl --request POST \
--url https://api.tavily.com/org-usage \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"organization_name": "Acme Inc",
"start_date": "2026-05-01",
"end_date": "2026-05-27",
"project_id": "<string>",
"depth": "advanced"
}
'import requests
url = "https://api.tavily.com/org-usage"
payload = {
"organization_name": "Acme Inc",
"start_date": "2026-05-01",
"end_date": "2026-05-27",
"project_id": "<string>",
"depth": "advanced"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
organization_name: 'Acme Inc',
start_date: '2026-05-01',
end_date: '2026-05-27',
project_id: '<string>',
depth: 'advanced'
})
};
fetch('https://api.tavily.com/org-usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tavily.com/org-usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'organization_name' => 'Acme Inc',
'start_date' => '2026-05-01',
'end_date' => '2026-05-27',
'project_id' => '<string>',
'depth' => 'advanced'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tavily.com/org-usage"
payload := strings.NewReader("{\n \"organization_name\": \"Acme Inc\",\n \"start_date\": \"2026-05-01\",\n \"end_date\": \"2026-05-27\",\n \"project_id\": \"<string>\",\n \"depth\": \"advanced\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tavily.com/org-usage")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"organization_name\": \"Acme Inc\",\n \"start_date\": \"2026-05-01\",\n \"end_date\": \"2026-05-27\",\n \"project_id\": \"<string>\",\n \"depth\": \"advanced\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tavily.com/org-usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"organization_name\": \"Acme Inc\",\n \"start_date\": \"2026-05-01\",\n \"end_date\": \"2026-05-27\",\n \"project_id\": \"<string>\",\n \"depth\": \"advanced\"\n}"
response = http.request(request)
puts response.read_body{
"organization": {
"name": "Acme Inc",
"filters": {
"start_date": "2026-05-01",
"end_date": "2026-05-27",
"project_id": null,
"depth": null
}
},
"totals": {
"usage": 1820,
"paygo_cost_usd": 12.71,
"request_count": 1760,
"by_type": {
"search": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"crawl": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"extract": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"map": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"research": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
}
}
},
"keys": [
{
"key": "...AB3xQ",
"name": "production-key",
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528,
"by_type": {
"search": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"crawl": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"extract": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"map": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
},
"research": {
"usage": 543,
"paygo_cost_usd": 4.34,
"request_count": 528
}
}
}
]
}{
"detail": {
"error": "Invalid start_date; expected format YYYY-MM-DD."
}
}{
"detail": {
"error": "Unauthorized: missing or invalid API key."
}
}{
"detail": {
"error": "Please authenticate with the organization owner's personal API key, not an organization API key."
}
}{
"detail": {
"error": "Organization not found or access denied."
}
}{
"detail": {
"error": "organization_name is required."
}
}{
"detail": {
"error": "Your request has been blocked due to excessive requests. Please reduce the rate of requests."
}
}{
"detail": {
"error": "Internal server error"
}
}{
"detail": {
"error": "Request timed out while fetching usage. Please try again or contact our team at support@tavily.com."
}
}Access to this API is an enterprise feature only. Talk to an expert to learn more.Authenticate with the organization owner’s personal API key — the key from the owner’s own personal account, not an organization or enterprise API key. Identify the organization by name in the request body. The report covers API keys in every workspace of the organization.
Authorizations
Body
application/json