> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Volumen de palabras clave
> Weekly and monthly volume projections for one keyword.
Each organization can look up 1,000 distinct keywords per UTC day; over
the cap returns 429 with Retry-After. Slices with two or fewer users are
omitted for privacy.
Proyecciones de volumen semanales y mensuales para una palabra clave, consultadas bajo demanda.
Pasa un `keyword`, un `matching_type` y un rango de fechas; acota con `regions`
y `platforms`.
* **`matching_type`:** `exact_match` o `phrase_match`.
* **Filas:** una por país, plataforma y período. La respuesta tiene filas semanales y mensuales; `frequency` las distingue (`Week - Monday Start` o `Month`).
* **Privacidad:** los segmentos con dos usuarios o menos se omiten de la respuesta.
* **`organization_id`:** obligatorio solo cuando tu clave de API tiene acceso a más de una organización. Selecciona la organización cuya cuota diaria usa la consulta.
**Cuota diaria de palabras clave.** Cada organización puede consultar 1,000 palabras clave
distintas por día UTC. Repetir una palabra clave que ya consultaste ese día
es gratis. Una palabra clave nueva que supere el límite devuelve `429` con los encabezados `X-KeywordQuota-*`
y `Retry-After`. Una consulta que no devuelve filas también cuenta
para la cuota.
```bash cURL theme={null}
curl -X POST https://api.tryprofound.com/v2/prompt-volumes/volume/on-the-fly \
-H "X-API-Key: " \
-H "Content-Type: application/json" \
-d '{
"keyword": "ai search optimization",
"matching_type": "phrase_match",
"start_date": "2026-08-01",
"end_date": "2026-08-31"
}'
```
## OpenAPI
````yaml POST /v2/prompt-volumes/volume/on-the-fly
openapi: 3.1.0
info:
title: External API
version: 0.60.2
x-scalar-sdk-installation:
- lang: Python
description: |-
```sh
pip install profound
```
- lang: TypeScript
description: |-
```sh
npm install @profoundai/client
```
- lang: Rust
description: |-
```sh
cargo add profound
```
servers:
- url: https://api.tryprofound.com
description: Production Server
security:
- APIKeyHeader:
- X-API-Key
- BearerAuth: []
paths:
/v2/prompt-volumes/volume/on-the-fly:
post:
tags:
- Prompt Volumes
summary: Get Keyword Volume
description: |-
Weekly and monthly volume projections for one keyword.
Each organization can look up 1,000 distinct keywords per UTC day; over
the cap returns 429 with Retry-After. Slices with two or fewer users are
omitted for privacy.
operationId: get_on_the_fly_volume_v2_prompt_volumes_volume_on_the_fly_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OtfVolumeRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/OtfVolumeResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
- BearerAuth: []
x-codeSamples:
- label: Python
lang: Python
source: |-
import os
from profound import Profound
client = Profound(
api_key=os.environ.get("PROFOUND_API_KEY"),
)
volume = client.prompt_volumes.volume.on_the_fly(
keyword="",
matching_type="exact_match",
start_date="2024-01-01",
end_date="2024-01-01",
)
print(volume)
- label: TypeScript
lang: TypeScript
source: |-
import Profound from '@profoundai/client';
const client = new Profound({
apiKey: process.env['PROFOUND_API_KEY'], // defaults to the PROFOUND_API_KEY env var
environment: 'production',
});
const volume = await client.promptVolumes.volume.onTheFly({
keyword: '',
matching_type: 'exact_match',
start_date: '2024-01-01',
end_date: '2024-01-01',
});
console.log(volume);
- label: rust
lang: rust
source: |-
use profound::*;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = ProfoundClient::builder()
.api_key(std::env::var("PROFOUND_API_KEY")?)
.build()?;
let response = client
.prompt_volumes()
.volume()
.on_the_fly(OtfVolumeRequest {
keyword: "".to_string(),
matching_type: OtfVolumeRequestMatchingType::ExactMatch,
start_date: chrono::Utc::now().date_naive(),
end_date: chrono::Utc::now().date_naive(),
regions: None,
platforms: None,
organization_id: None,
})
.send()
.await?;
println!("{:?}", response);
Ok(())
}
components:
schemas:
OtfVolumeRequest:
properties:
keyword:
type: string
title: Keyword
matching_type:
type: string
enum:
- exact_match
- phrase_match
title: Matching Type
start_date:
type: string
format: date
title: Start Date
end_date:
type: string
format: date
title: End Date
regions:
items:
type: string
type: array
title: Regions
description: >-
ISO 3166-1 alpha-3 country codes (e.g. USA). Omit to include every
region.
platforms:
items:
type: string
enum:
- chatgpt.com
- gemini.google.com
- perplexity.ai
type: array
title: Platforms
description: Platforms to restrict to. Omit to include every platform.
organization_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Organization Id
description: >-
Organization whose daily keyword allowance is used. Required in the
JSON request body for API keys with multiple organizations that have
API access. If omitted or null, defaults to the API key's sole
organization with API access or the token's active organization. For
OAuth/M2M tokens, any supplied organization_id must match the
token's organization.
type: object
required:
- keyword
- matching_type
- start_date
- end_date
title: OtfVolumeRequest
OtfVolumeResponse:
properties:
info:
$ref: '#/components/schemas/VolumeResponseInfo'
data:
items:
$ref: '#/components/schemas/OtfVolumeData'
type: array
title: Data
type: object
required:
- info
- data
title: OtfVolumeResponse
description: Response wrapper with metadata and data array.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
VolumeResponseInfo:
properties:
total_rows:
type: integer
title: Total Rows
truncated:
type: boolean
title: Truncated
default: false
query:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Query
type: object
required:
- total_rows
title: VolumeResponseInfo
description: |-
Metadata for volume query response.
truncated indicates if results hit MAX_ROWS limit.
OtfVolumeData:
properties:
country_code:
type: string
title: Country Code
platform:
type: string
title: Platform
matching_type:
type: string
title: Matching Type
frequency:
type: string
title: Frequency
date:
type: string
format: date
title: Date
volume:
type: number
title: Volume
type: object
required:
- country_code
- platform
- matching_type
- frequency
- date
- volume
title: OtfVolumeData
description: |-
Single projected volume row.
Each keyword query returns both weekly and monthly rows in one response;
frequency distinguishes them and matches the fast table's values
('Week - Monday Start' / 'Month').
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````