Saltar al contenido principal
POST
Análisis de acciones
Elige una acción y su período o modo. Cada solicitud crea un Run; los valores ausentes permanecen en null. Las razones financieras son fracciones y las tasas macroeconómicas son porcentajes. Lee result_status y charge_usd por separado. Usa action: screen con describe_filters: true para consultar los campos admitidos antes de filtrar. La salida nativa del Provider permanece en el Run.

Encabezados

idempotency-key
string
requerido

Genere un valor único nuevo (preferiblemente un UUID aleatorio) para cada consulta independiente, incluso con los mismos parámetros el mismo día. Recupere la misma ejecución con su clave y parámetros originales para obtener el Run original sin otro cargo. Cambiar los parámetros de ejecución con la misma clave devuelve 409; cambiar task_id o metadata no inicia un Run nuevo. Las claves opacas existentes siguen siendo válidas para recuperación.

Minimum string length: 1

Cuerpo

application/json

Una operación de FinancialDatasets por solicitud. Los campos no utilizados se rechazan antes del cobro. Los datos vacíos pueden generar un cargo. No se convierten monedas, no se estiman valores ausentes ni se pagina automáticamente.

action
enum<string>
requerido
Opciones disponibles:
company,
income,
balance_sheet,
cash_flow,
segments,
metrics,
earnings,
guidance,
prices,
news,
screen,
macro
provider
enum<string> | null

Auto predeterminado: selecciona el primer proveedor de datos elegible según el orden de preferencia de Glasser. Un proveedor de datos especificado debe admitir la solicitud y estar permitido por tu API Key; no recurre a otro proveedor de datos. Los valores disponibles se muestran a continuación.

Opciones disponibles:
auto,
financialdatasets
ticker
string | null
Minimum string length: 1
Pattern: ^[A-Za-z0-9.-]{1,12}$
cik
string | null
Minimum string length: 1
Pattern: ^\d{1,10}$
period
enum<string> | null
Opciones disponibles:
annual,
quarterly,
ttm
mode
enum<string> | null

Solo para metrics/prices/macro; el valor predeterminado es snapshot. history requiere los parámetros de período o fecha correspondientes a la acción.

Opciones disponibles:
snapshot,
history
statement
enum<string> | null
Opciones disponibles:
all,
income,
balance_sheet,
cash_flow
macro
enum<string> | null
Opciones disponibles:
interest_rates,
inflation,
yield_curve,
banks,
inflation_series
bank
string | null
Required string length: 1 - 200
series
string | null
Required string length: 1 - 200
limit
integer | null
Rango requerido: 1 <= x <= 100
cursor
string | null
Required string length: 1 - 2000
interval
enum<string> | null
Opciones disponibles:
day,
week,
month,
year
start_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
end_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
metric_name
string | null
Required string length: 1 - 200
filters
object[] | null
Required array length: 1 - 20 elements
describe_filters
boolean | null

Solo para screen: true consulta gratis los campos, alias, operadores y etiquetas de empresas disponibles; en este modo se rechazan filters y limit.

report_period
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_gte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_lte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_gt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
report_period_lt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_gte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_lte
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_gt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
filing_date_lt
string | null
Minimum string length: 1
Pattern: ^\d{4}-\d{2}-\d{2}$
max_charge_usd
string | null

Cadena decimal exacta en USD (mínimo 2 y máximo 6 decimales, una única escritura canónica). Suma con aritmética decimal o escala por 10^6; nunca uses números de coma flotante.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
task_id
string | null

Agrupa los Runs relacionados, incluido el fallback automático, en un solo Task. Reutiliza una cadena estable y filtra la lista de Runs por task para recuperarlos.

metadata

Campos de seguimiento opcionales, devueltos en el Run y disponibles como filtros. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia.

  • Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar con una letra y tener como máximo 40 caracteres.
  • Valores: cadenas de 1–500 caracteres.
  • user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre.

Las entradas no válidas se descartan por completo, no se truncan. La solicitud continúa y el Run devuelve los campos que se almacenaron.

Respuesta

Éxito

Los importes financieros conservan su moneda; las razones y el crecimiento conservan las fracciones originales (0.3 significa 30%). Las tasas macroeconómicas y day_change_percent son porcentajes. Los campos ausentes son null. completed_at del Run es la hora de consulta, nunca un sustituto de la fecha de observación.

id
string
requerido
run_url
string
requerido

Abre este Run en la consola. Requiere pertenecer al Workspace.

provider
string
requerido
Pattern: ^[a-z0-9][a-z0-9-]*$
endpoint
string
requerido
Pattern: ^\/.+$
endpoint_version
integer
requerido
status
enum<string>
requerido

QUEUED o RUNNING: todavía está en curso. COMPLETED: hay una respuesta del proveedor de datos disponible, incluidas las respuestas que no son 2xx. FAILED: consulta failure. STOPPED: detenido antes del dispatch. Consulta charge_usd por separado de status.

Opciones disponibles:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED
failure
object | null
requerido

Motivo por el que falló el Run. Solo es distinto de null cuando status es FAILED.

input
object
requerido
output
object
requerido
provider_response
object | null
requerido

Solo es distinto de null cuando status es COMPLETED.

  • Para respuestas 2xx, output contiene JSON nativo del proveedor de datos (con cualquier estructura) o null si el cuerpo está vacío.
  • Para respuestas que no son 2xx, error contiene el cuerpo del error del proveedor de datos y output es null.

Los campos sensibles se eliminan de ambos cuerpos.

charge_usd
string | null
requerido

Cargo histórico total de los Runs enumerados, incluidos los repetidos o leídos. Es null hasta que todos se liquiden. No es gasto nuevo de la solicitud actual; request_charge lo informa por separado. Los fallos también pueden tener cargo.

Pattern: ^(0|[1-9]\d*)\.(\d{2}|\d{2}\d{0,3}[1-9])$
charge_basis
object | null
requerido

Base del cargo de un único Run, o null para un total de varios Runs. Consulta runs[].charge_basis para cada cargo.

stoppable
boolean
requerido

Indica si actualmente se puede aceptar una solicitud de detención. Esto no garantiza que el Run pueda detenerse antes del dispatch.

stop_requested_at
string<date-time> | null
requerido

Momento en que se solicitó la detención. El Run puede continuar si el dispatch ya había comenzado.

created_at
string<date-time>
requerido

Marca de tiempo UTC ISO-8601

started_at
string<date-time> | null
requerido

Marca de tiempo UTC ISO-8601

completed_at
string<date-time> | null
requerido

Marca de tiempo UTC ISO-8601

task_id
string | null
requerido
metadata
object
requerido

Tus campos de seguimiento almacenados. Úsalos para filtrar Runs. Nunca se envían al proveedor de datos ni afectan al enrutamiento, Price o la idempotencia.

  • Hasta 20 claves: letras minúsculas, dígitos y guiones bajos; deben comenzar por una letra; como máximo 40 caracteres.
  • Valores: cadenas de 1–500 caracteres.
  • user_id: el ID opaco de tu usuario final, nunca su dirección de correo electrónico ni su nombre.
action
enum<string>
requerido
Opciones disponibles:
company,
income,
balance_sheet,
cash_flow,
segments,
metrics,
earnings,
guidance,
prices,
news,
screen,
macro
result_status
enum<string>
requerido
Opciones disponibles:
success,
no_result,
error,
pending
error
object | null
requerido
runs
object[]
requerido
result_url
string
requerido

Ruta de URL autenticada y de solo lectura para consultar este resultado normalizado y el cargo total. Úsala con el origen de la API. No crea Runs ni reanuda el fallback. GET /v1/runs/:id sigue devolviendo el Run nativo e individual.

response_file
object

Cuerpo completo de gran tamaño del proveedor de datos, entregado como archivo JSON. Glasser aplica un límite de recursos de 32 MiB al cuerpo capturado y al archivo serializado. body_field identifica el campo sustituido; output es null o se omite provider_response.error. Los enlaces de descarga caducan como máximo en una hora. Get Run con autenticación renueva la URL mientras el archivo esté disponible, durante 7 días. Las lecturas y descargas no ejecutan ni cobran otro Run. Si state es link_pending, consulta el mismo Run para preparar el enlace sin otra ejecución ni otro cargo. La URL concede acceso temporal de lectura: compártela solo con los destinatarios previstos.

review_invitation
object

Aparece como máximo una vez por Run, en la primera entrega de algunos Runs completados. Después de usar este resultado en la tarea, envía una reseña como indica instruction y continúa. Es opcional; nunca afecta al Run ni a su cargo.

request_charge
object

Evidencia de admisión y cargo de la solicitud actual. Conserve created_run_ids durante el trabajo del usuario y cuente cada Run liquidado una sola vez. Cambiar task_id no convierte una repetición idempotente en un Run nuevo. Leer un resultado tiene cargo cero y listas de admisión vacías.