OneMetrics
Empezar gratis
API v1

Referencia de la API

La misma API que usan nuestros conectores para Looker Studio, Google Sheets, Power BI y Excel. Consulta tus datos de marketing y e-commerce con una sola solicitud.

Crear clave de APIOpenAPI

Introducción

Todas las solicitudes van a la URL base de abajo por HTTPS. Las respuestas son JSON (UTF-8), salvo que pidas format=csv o format=ndjson.

URL base
https://onemetrics.co/api/v1
  • Las fechas usan el formato YYYY-MM-DD y son días de calendario inclusivos en la zona horaria de cada fuente.
  • Las marcas de tiempo usan ISO 8601 en UTC.
  • Los importes monetarios vienen en unidades mayores (por ejemplo 12.5 = 12,50 USD).
  • Los ID de fuentes, clientes y consultas guardadas son UUID de OneMetrics, no los ID de la plataforma.

Autenticación

Envía un token en la cabecera Authorization de cada solicitud:

HTTP
Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Clave de API (mk_live_…): créala en Claves de API. Pertenece a un espacio de trabajo y puede limitarse a algunos clientes. Ideal para scripts, ETL y BigQuery.
  • Token de acceso OAuth (mko_…): lo emite nuestro servidor OAuth 2.0 a integraciones como Looker Studio, Google Sheets o Power BI. Dura 1 hora.

Los tokens tienen alcances (scopes): read permite listar conectores, fuentes, clientes y consultas guardadas; query permite ejecutar consultas. Las claves nuevas incluyen ambos.

Cabecera de destino

Opcional. Indica desde qué herramienta llega la solicitud para que veas el uso por destino en la app. Valor por defecto: api.

HTTP
X-OneMetrics-Destination: api | looker_studio | google_sheets | power_bi | excel | bigquery

Errores

Los errores devuelven el código HTTP correspondiente y un sobre JSON con un code estable que puedes usar en tu lógica. message está pensado para personas y puede cambiar.

JSON
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Unknown field: foo",
    "details": {}
  }
}
CódigoHTTPSignificado
INVALID_REQUEST400La solicitud no es válida: campo desconocido, JSON mal formado, combinación de campos no permitida…
UNAUTHORIZED401Falta el token, no es válido, caducó o fue revocado.
PLAN_LIMIT402Se alcanzó un límite del plan (consultas, filas, historial o destino no incluido).
FORBIDDEN403El token no tiene el alcance necesario o no tiene acceso a ese cliente o fuente.
NOT_FOUND404El recurso no existe o no pertenece a tu espacio de trabajo.
AUTH_EXPIRED409Una conexión con la plataforma necesita volver a autorizarse en Conexiones.
RATE_LIMITED429Demasiadas solicitudes. Respeta la cabecera Retry-After (segundos).
INTERNAL500Error inesperado de OneMetrics. Reinténtalo; si persiste, escríbenos.
UPSTREAM_ERROR502La plataforma de origen (Meta, Shopify…) devolvió un error.
TIMEOUT504La consulta tardó demasiado. Usa un rango más corto o menos campos.

Límites de velocidad y uso

Por defecto se admiten 120 solicitudes por minuto por token. Si lo superas recibirás 429 RATE_LIMITED con la cabecera Retry-After. Los feeds secretos admiten 30 solicitudes por minuto por consulta.

Cada respuesta de consulta incluye cabeceras con el uso del mes. Si falta la cabecera -Limit, ese recurso es ilimitado en tu plan.

Cabeceras
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Usage-Queries: 1824
X-Usage-Queries-Limit: 100000
X-Usage-Rows: 245120
X-Usage-Rows-Limit: 20000000

Endpoints

Todas las rutas son relativas a la URL base. Las rutas que lo requieren aceptan la cabecera Authorization.

Token actual

GET/me

Devuelve el usuario, el espacio de trabajo, el plan con sus límites y el uso del mes para el token. Útil para probar credenciales.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/me" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY"

Ejemplo de respuesta

JSON
{
  "user": { "id": "8c1d…", "email": "ana@agency.com", "fullName": "Ana Gómez", "locale": "es" },
  "workspace": { "id": "4f9c…", "name": "Acme Agency", "slug": "acme", "timezone": "America/Bogota", "currency": "COP" },
  "auth": { "kind": "api_key", "scopes": ["query", "read"], "clientRestricted": false },
  "plan": { "code": "pro", "kind": "connectors", "status": "active", "limits": { "max_queries_month": 100000, "…": "…" } },
  "usage": { "queries": 1824, "rows": 245120 }
}

Listar conectores

GET/connectors

Conectores activos en el espacio de trabajo con sus opciones (por ejemplo, ventanas de atribución) y el número de campos.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/connectors" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY"

Ejemplo de respuesta

JSON
[
  {
    "id": "meta_ads",
    "name": "Meta Ads",
    "description": "Facebook & Instagram ads performance",
    "category": "ads",
    "icon": "/connectors/meta_ads.svg",
    "options": [{ "id": "attribution_windows", "type": "multiselect", "…": "…" }],
    "fieldCount": 182
  }
]

Campos de un conector

GET/connectors/{id}/fields

Lista de campos públicos (PublicField) del conector, incluidas las dimensiones de plataforma.

ParámetroUbicaciónTipoDescripción
idobligatorioRutastringID del conector, por ejemplo meta_ads o shopify.
localeConsultaes | enIdioma de etiquetas y grupos. Por defecto, el del token.
destinationConsultastringCon looker_studio añade los tipos de Looker Studio en looker.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/connectors/meta_ads/fields?locale=es&destination=looker_studio" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY"

Ejemplo de respuesta

JSON
{
  "fields": [
    { "id": "spend", "kind": "metric", "dataType": "currency", "label": "Importe gastado", "group": "Rendimiento",
      "aggregation": "sum", "isDefault": true,
      "looker": { "dataType": "NUMBER", "semanticType": "CURRENCY_USD" } },
    { "id": "ctr", "kind": "metric", "dataType": "percent", "label": "CTR", "group": "Rendimiento",
      "aggregation": "ratio", "isDefault": false,
      "derived": { "numerator": "clicks", "denominator": "impressions" } }
  ]
}

Listar clientes

GET/clients

Clientes del espacio de trabajo visibles para el token.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/clients" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY"

Ejemplo de respuesta

JSON
[
  { "id": "0b7e…", "name": "Tienda Andina", "color": "#1a73e8" }
]

Listar fuentes de datos

GET/sources

Cuentas publicitarias, tiendas y demás fuentes conectadas, con su moneda, zona horaria, cliente y estado de la conexión.

ParámetroUbicaciónTipoDescripción
connectorConsultastringFiltra por conector.
clientConsultauuidFiltra por cliente.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/sources?connector=meta_ads" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY"

Ejemplo de respuesta

JSON
[
  {
    "id": "4f9c…",
    "connector": "meta_ads",
    "name": "Tienda Andina – Ads",
    "externalId": "act_123456789",
    "currency": "COP",
    "timezone": "America/Bogota",
    "client": { "id": "0b7e…", "name": "Tienda Andina" },
    "connection": { "id": "a1d2…", "name": "Meta – ana@agency.com", "status": "active" },
    "lastSyncedAt": "2026-10-26T13:00:00Z"
  }
]

Ejecutar una consulta

POST/query

Ejecuta un QueryRequest y devuelve un QueryResult. Es el endpoint principal de la API.

ParámetroUbicaciónTipoDescripción
formatConsultajson | csv | ndjson | lookerFormato de la respuesta. Por defecto json.
bodyobligatorioCuerpoQueryRequestCuerpo JSON con el QueryRequest.
Para resultados grandes, pagina con limit y offset: meta.totalRows indica el total de filas antes de paginar.

Ejemplo de solicitud

curl -X POST "https://onemetrics.co/api/v1/query?format=json" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connector": "meta_ads",
  "fields": ["date", "campaign_name", "spend", "impressions", "ctr", "actions_purchase"],
  "dateRange": { "preset": "last_30_days" },
  "filters": [{ "field": "campaign_name", "op": "contains", "value": "Black Friday" }],
  "sort": [{ "field": "spend", "direction": "desc" }],
  "limit": 1000,
  "currency": "USD"
}'

Ejemplo de respuesta

JSON
{
  "columns": [
    { "id": "date", "label": "Date", "kind": "dimension", "dataType": "date" },
    { "id": "campaign_name", "label": "Campaign name", "kind": "dimension", "dataType": "string" },
    { "id": "spend", "label": "Amount spent", "kind": "metric", "dataType": "currency" },
    { "id": "ctr", "label": "CTR", "kind": "metric", "dataType": "percent" }
  ],
  "rows": [
    { "date": "2026-10-01", "campaign_name": "Black Friday – Prospecting", "spend": 412.5, "ctr": 0.0183 }
  ],
  "totals": { "spend": 12840.32 },
  "meta": {
    "connector": "meta_ads",
    "range": { "start": "2026-09-26", "end": "2026-10-25" },
    "rowCount": 30,
    "totalRows": 30,
    "servedFrom": "stored",
    "currency": "USD",
    "durationMs": 120,
    "dataFreshness": "2026-10-26T13:00:00Z",
    "warnings": []
  }
}

Ejecutar una consulta (GET)

GET/query

Igual que POST /query, con los parámetros en la URL. Útil para herramientas que solo hacen GET.

ParámetroUbicaciónTipoDescripción
connectorobligatorioConsultastringID del conector.
fieldsobligatorioConsultaa,b,cID de campos separados por comas.
sourcesConsultauuid,uuidID de fuentes separados por comas.
clientConsultauuidLimita a las fuentes de un cliente.
presetConsultaDatePresetPeriodo predefinido. Ver periodos.
startConsultaYYYY-MM-DDFecha inicial (con end).
endConsultaYYYY-MM-DDFecha final (con start).
filtersConsultaJSONArreglo de filtros en JSON (codificado para URL).
sortConsulta-spend,dateCampos separados por comas; prefijo - para descendente.
limitConsultaintegerMáximo de filas.
offsetConsultaintegerFilas a omitir.
currencyConsultaISO 4217Convierte las métricas monetarias a esta moneda.
timezoneConsultaIANAZona horaria para agrupar datos con marca de tiempo.
freshnessConsultaauto | stored | liveOrigen de los datos.
totalsConsultabooleantrue para incluir totales.
optionsConsultaJSONOpciones del conector en JSON.
formatConsultajson | csv | ndjson | lookerFormato de la respuesta.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/query?connector=meta_ads&fields=date,campaign_name,spend&preset=last_7_days&sort=-spend&format=csv" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY"

Ejemplo de respuesta

CSV
date,campaign_name,spend
2026-10-25,Black Friday – Prospecting,412.5
2026-10-25,Retargeting – Cart,188.1

Listar consultas guardadas

GET/saved-queries

Consultas guardadas del espacio de trabajo. Cada elemento incluye connector y la request completa para que puedas abrirla o modificarla.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/saved-queries" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY"

Ejemplo de respuesta

JSON
[
  {
    "id": "6a3b…",
    "name": "Meta Ads · Rendimiento mensual",
    "connector": "meta_ads",
    "clientId": null,
    "request": { "connector": "meta_ads", "fields": ["date", "spend"], "dateRange": { "preset": "last_month" } },
    "lastRunAt": "2026-10-26T08:00:00Z",
    "updatedAt": "2026-10-20T15:12:00Z"
  }
]

Ejecutar una consulta guardada

GET/saved-queries/{id}/run

Ejecuta una consulta guardada. Puedes reemplazar su rango de fechas con preset o con start y end.

ParámetroUbicaciónTipoDescripción
idobligatorioRutauuidID de la consulta guardada (en la app: Consultas guardadas → ⋯ → Copiar ID).
formatConsultajson | csv | ndjson | lookerFormato de la respuesta.
presetConsultaDatePresetReemplaza el periodo.
startConsultaYYYY-MM-DDFecha inicial (con end).
endConsultaYYYY-MM-DDFecha final (con start).

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/saved-queries/6a3b…/run?format=json&preset=last_month" \
  -H "Authorization: Bearer $ONEMETRICS_API_KEY"

Ejemplo de respuesta

JSON
{
  "columns": [
    { "id": "date", "label": "Date", "kind": "dimension", "dataType": "date" },
    { "id": "campaign_name", "label": "Campaign name", "kind": "dimension", "dataType": "string" },
    { "id": "spend", "label": "Amount spent", "kind": "metric", "dataType": "currency" },
    { "id": "ctr", "label": "CTR", "kind": "metric", "dataType": "percent" }
  ],
  "rows": [
    { "date": "2026-10-01", "campaign_name": "Black Friday – Prospecting", "spend": 412.5, "ctr": 0.0183 }
  ],
  "totals": { "spend": 12840.32 },
  "meta": {
    "connector": "meta_ads",
    "range": { "start": "2026-09-26", "end": "2026-10-25" },
    "rowCount": 30,
    "totalRows": 30,
    "servedFrom": "stored",
    "currency": "USD",
    "durationMs": 120,
    "dataFreshness": "2026-10-26T13:00:00Z",
    "warnings": []
  }
}

Feed secreto

GET/feeds/{token}.{csv|json}Sin autenticación

URL secreta de una consulta guardada en CSV o JSON, sin cabecera Authorization: el token de la URL es la credencial. Pensada para Excel, Power BI y la función IMPORTDATA de Google Sheets.

ParámetroUbicaciónTipoDescripción
tokenobligatorioRutastringToken del feed (en la app: Consultas guardadas → ⋯ → URL del feed).
presetConsultaDatePresetReemplaza el periodo.
startConsultaYYYY-MM-DDFecha inicial (con end).
endConsultaYYYY-MM-DDFecha final (con start).
destConsultaexcel | power_bi | google_sheetsDestino para las estadísticas de uso. Por defecto excel.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/feeds/Xk3…9pQ.csv?preset=last_30_days"

Ejemplo de respuesta

CSV
date,campaign_name,spend,impressions
2026-10-25,Black Friday – Prospecting,412.5,38120

Documento OpenAPI

GET/openapi.jsonSin autenticación

Especificación OpenAPI 3.1 de la API, pública. Impórtala en Postman, Insomnia o tu generador de clientes.

Ejemplo de solicitud

curl "https://onemetrics.co/api/v1/openapi.json"

Ejemplo de respuesta

JSON
{ "openapi": "3.1.0", "info": { "title": "OneMetrics API", "version": "1" }, "paths": { "…": "…" } }

QueryRequest

Describe qué datos quieres. Es el mismo contrato para la API, Looker Studio, Sheets, Power BI, Excel y las exportaciones a BigQuery.

JSON
{
  "connector": "meta_ads",
  "sources": ["4f9c…"],
  "fields": ["date", "campaign_name", "spend", "impressions", "ctr", "actions_purchase"],
  "dateRange": { "preset": "last_30_days" },
  "filters": [{ "field": "campaign_name", "op": "contains", "value": "Black Friday" }],
  "sort": [{ "field": "spend", "direction": "desc" }],
  "limit": 1000,
  "currency": "USD",
  "options": { "attribution_windows": ["7d_click", "1d_view"] }
}
CampoTipoPredeterminadoDescripción
connectorobligatoriostring—ID del conector a consultar.
fieldsobligatoriostring[] (1–200)—ID de dimensiones y métricas, en el orden de las columnas. Consulta la lista con GET /connectors/{id}/fields.
sourcesuuid[][]ID de fuentes de OneMetrics. Vacío = todas las fuentes del conector (o del cliente).
clientuuid—Limita la consulta a las fuentes asignadas a un cliente.
dateRange{ preset } | { start, end }{ "preset": "last_28_days" }Un periodo predefinido o un rango con start y end (inclusivo).
filtersFilter[] (≤ 50)[]Condiciones que deben cumplir las filas. Ver filtros.
sortSort[] (≤ 10)[]Orden: { field, direction: "asc" | "desc" }.
limitinteger (≤ 1 000 000)—Máximo de filas devueltas.
offsetinteger0Filas a omitir (paginación).
currencyISO 4217—Convierte todas las métricas monetarias con tipos de cambio diarios.
timezoneIANA—Zona horaria para agrupar datos con marca de tiempo (por ejemplo, pedidos de Shopify).
optionsobject{}Opciones propias del conector, por ejemplo attribution_windows en Meta Ads.
freshness"auto" | "stored" | "live""auto"stored usa solo datos sincronizados, live consulta siempre la plataforma y auto elige la mejor opción.
totalsbooleanfalseAñade una fila de totales calculada con la agregación de cada métrica.

Periodos predefinidos

Úsalos en dateRange.preset o en el parámetro preset. Se calculan en la zona horaria de cada fuente; las semanas empiezan el lunes.

  • todayHoy
  • yesterdayAyer
  • last_7_daysÚltimos 7 días
  • last_14_daysÚltimos 14 días
  • last_28_daysÚltimos 28 días
  • last_30_daysÚltimos 30 días
  • last_90_daysÚltimos 90 días
  • last_365_daysÚltimos 365 días
  • this_weekEsta semana
  • last_weekSemana pasada
  • this_monthEste mes
  • last_monthMes pasado
  • this_quarterEste trimestre
  • last_quarterTrimestre pasado
  • this_yearEste año
  • last_yearAño pasado
  • month_to_dateMes en curso
  • year_to_dateAño en curso
  • maximumMáximo disponible

Filtros

Cada filtro es { field, op, value }. Todos los filtros se combinan con Y. in y not_in reciben un arreglo; is_null e is_not_null no llevan valor.

OperadorDescripción
eqIgual a
neqDistinto de
gtMayor que
gteMayor o igual que
ltMenor que
lteMenor o igual que
inEstá en la lista
not_inNo está en la lista
containsContiene el texto
not_containsNo contiene el texto
starts_withEmpieza por
ends_withTermina en
regexCoincide con la expresión regular
is_nullEstá vacío
is_not_nullNo está vacío
JSON
[
  { "field": "campaign_name", "op": "contains", "value": "Black Friday" },
  { "field": "spend", "op": "gte", "value": 100 },
  { "field": "data_source_id", "op": "in", "value": ["4f9c…", "7d21…"] },
  { "field": "adset_name", "op": "is_not_null" }
]

QueryResult

columns describe cada columna en el orden de fields; rows trae un objeto por fila; totals aparece si pediste totals: true.

  • meta.servedFrom: stored (datos sincronizados), live (consulta en vivo), cache o mixed.
  • meta.dataFreshness: cuándo se actualizaron por última vez los datos guardados.
  • meta.totalRows: filas antes de aplicar offset y limit.
  • meta.warnings: avisos no bloqueantes, por ejemplo métricas que no se pudieron combinar.
JSON
{
  "columns": [
    { "id": "date", "label": "Date", "kind": "dimension", "dataType": "date" },
    { "id": "campaign_name", "label": "Campaign name", "kind": "dimension", "dataType": "string" },
    { "id": "spend", "label": "Amount spent", "kind": "metric", "dataType": "currency" },
    { "id": "ctr", "label": "CTR", "kind": "metric", "dataType": "percent" }
  ],
  "rows": [
    { "date": "2026-10-01", "campaign_name": "Black Friday – Prospecting", "spend": 412.5, "ctr": 0.0183 }
  ],
  "totals": { "spend": 12840.32 },
  "meta": {
    "connector": "meta_ads",
    "range": { "start": "2026-09-26", "end": "2026-10-25" },
    "rowCount": 30,
    "totalRows": 30,
    "servedFrom": "stored",
    "currency": "USD",
    "durationMs": 120,
    "dataFreshness": "2026-10-26T13:00:00Z",
    "warnings": []
  }
}

Formatos de salida

FormatoDescripción
format=jsonPredeterminado. QueryResult completo.
format=csvEncabezados con los ID de campo, separador coma, UTF-8. Ideal para hojas de cálculo.
format=ndjsonUn objeto JSON por línea. Ideal para cargas por streaming y BigQuery.
format=lookerFormato del conector de Looker Studio: schema y rows[].values en el orden de fields, con fechas YYYYMMDD.
format=looker
{
  "schema": [{ "name": "date", "dataType": "STRING" }, { "name": "spend", "dataType": "NUMBER" }],
  "rows": [{ "values": ["20261001", 412.5] }]
}

PublicField

TypeScript
{
  id: string,
  kind: "dimension" | "metric",
  dataType: "string" | "integer" | "number" | "currency" | "percent" | "boolean" | "date" | "datetime" | "json",
  label: string,
  description?: string,
  group: string,
  aggregation: "sum" | "avg" | "min" | "max" | "count" | "count_distinct" | "ratio" | "none",
  isDefault: boolean,
  derived?: { numerator: string, denominator: string, multiplier?: number },  // ratio metrics
  looker?: { dataType: "STRING" | "NUMBER" | "BOOLEAN", semanticType: string } // destination=looker_studio
}

Las métricas de tipo ratio (CTR, CPC, ROAS…) incluyen derived: { numerator, denominator, multiplier? } para que puedas recalcularlas correctamente al agrupar: SUM(numerator) / SUM(denominator) × multiplier.

Todos los conectores incluyen además estas dimensiones de plataforma: data_source_id, data_source_name, data_source_external_id, client_id, client_name y source_currency.

Consultas guardadas y feeds secretos

Guarda una consulta en el Explorador de la app y ejecútala por ID con GET /saved-queries/{id}/run. Si necesitas una URL sin cabeceras, genera su URL del feed:

URL
https://onemetrics.co/api/v1/feeds/{token}.csv

Servidor OAuth 2.0

  • GEThttps://onemetrics.co/oauth/authorizePágina de inicio de sesión, elección de espacio de trabajo y consentimiento. Parámetros: response_type=code, client_id, redirect_uri, state, scope, code_challenge, code_challenge_method=S256.
  • POSThttps://onemetrics.co/api/oauth/tokenCanjea el código o un token de actualización (application/x-www-form-urlencoded): grant_type=authorization_code | refresh_token, code, redirect_uri, client_id, client_secret o code_verifier, refresh_token.
  • POSThttps://onemetrics.co/api/oauth/revokeRevoca un token de acceso o de actualización: token=.

Para integraciones que actúan en nombre de un usuario usamos el flujo authorization code con PKCE (S256). Los tokens de acceso duran 1 hora y los de actualización 180 días; estos últimos rotan en cada uso.

curl
curl -X POST "https://onemetrics.co/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://example.com/callback \
  -d client_id=$CLIENT_ID \
  -d code_verifier=$CODE_VERIFIER
JSON
{
  "access_token": "mko_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "query read"
}

Los usuarios pueden revisar y revocar las aplicaciones autorizadas en Cuenta → Autorizaciones. ¿Quieres registrar tu propia integración? Escríbenos.

OpenAPI

La especificación completa está disponible en formato OpenAPI 3.1 para generar clientes o probar la API en tu herramienta favorita.

¿Necesitas ayuda con la integración?

Nuestro equipo técnico responde en español e inglés.

Contactar soporte