Cómo usar la API pública de Postoria
La API pública de Postoria te permite conectar herramientas externas, scripts y sistemas internos con Postoria.
Puedes utilizarla para crear y gestionar espacios de trabajo, conectar y reconectar cuentas sociales, listar las cuentas conectadas, subir recursos multimedia, crear y gestionar publicaciones y obtener analíticas actuales o agregadas. También puedes obtener analíticas diarias de cuentas y resúmenes de su rendimiento.
La API pública está disponible en los planes Pro y Agency.
Antes de empezar
Estos son los aspectos principales que debes conocer antes de utilizar la API:
- Necesitas un plan Pro o Agency activo.
- Cada cuenta de Postoria puede tener una clave de API activa.
- Las claves se aplican a toda la cuenta, no a un espacio de trabajo concreto.
- Los endpoints específicos de un espacio requieren un
workspace_iden la URL. - La API utiliza autenticación mediante token Bearer.
- El límite es de 300 solicitudes cada 5 minutos por cuenta.
- El procesamiento de recursos multimedia es asíncrono.
- Las respuestas utilizan campos JSON en
snake_case. - La versión v1 utiliza el prefijo de ruta
/v1.
URL base
Utiliza esta URL base:
https://api.postoria.io/v1
La documentación de la API está disponible aquí: https://api.postoria.io/v1/docs/.
El documento OpenAPI está disponible aquí: https://api.postoria.io/v1/openapi.json.
Crea una clave de API
- Abre Postoria.
- Ve a Configuración.
- Busca la sección API pública, servidor MCP e integración con n8n.
- Haz clic en Crear clave de API.
- Copia la clave y guárdala de forma segura.
Postoria solo muestra la clave completa una vez. Después de cerrar el cuadro de diálogo, únicamente verás su prefijo.
Si pierdes la clave, revócala y crea una nueva.
Autentica las solicitudes
Envía la clave en el encabezado Authorization:
Authorization: Bearer pst_live_your_api_key
Ejemplo:
curl https://api.postoria.io/v1/workspaces \
-H "Authorization: Bearer pst_live_your_api_key"
Si la clave no está presente, no es válida o ha sido revocada, Postoria devuelve 401 invalid_api_key.
Formato de las respuestas
Las respuestas de un único recurso devuelven directamente el objeto.
Las respuestas de listas utilizan este formato:
{
"data": [],
"pagination": {
"has_more": false,
"next_cursor": null,
"next": null
}
}
Cuando un endpoint de lista admite paginación, has_more indica si hay otra página disponible. Utiliza next para solicitarla directamente o envía el valor devuelto en next_cursor como parámetro de consulta cursor.
Las respuestas de error utilizan este formato:
{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid.",
"param": null,
"details": null,
"request_id": "req_abc123"
}
}
Límite de solicitudes
La API pública permite:
300 requests per 5 minutes per account
Si superas el límite, Postoria devuelve 429 rate_limit_exceeded con encabezados para indicar cuándo reintentar.
Ejemplo:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1770000000
Endpoints
La versión v1 de la API pública incluye estos endpoints:
GET /v1/workspaces
GET /v1/workspaces/{workspace_id}
POST /v1/workspaces
PATCH /v1/workspaces/{workspace_id}
DELETE /v1/workspaces/{workspace_id}
GET /v1/social-account-connection-options
POST /v1/workspaces/{workspace_id}/social-account-connections
GET /v1/workspaces/{workspace_id}/social-account-connections/{state}
POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts
POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect
GET /v1/workspaces/{workspace_id}/social-accounts
PATCH /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
GET /v1/workspaces/{workspace_id}/queues
POST /v1/workspaces/{workspace_id}/media/uploads
POST /v1/workspaces/{workspace_id}/media/{media_id}/complete
POST /v1/workspaces/{workspace_id}/media/imports
GET /v1/workspaces/{workspace_id}/media/{media_id}
POST /v1/workspaces/{workspace_id}/posts
GET /v1/workspaces/{workspace_id}/posts
GET /v1/workspaces/{workspace_id}/posts/{post_id}
DELETE /v1/workspaces/{workspace_id}/posts/{post_id}
GET /v1/workspaces/{workspace_id}/analytics/posts
GET /v1/workspaces/{workspace_id}/analytics/post-performance/summary
GET /v1/workspaces/{workspace_id}/analytics/accounts
GET /v1/workspaces/{workspace_id}/analytics/account-performance/summary
Lista los espacios de trabajo
Utiliza este endpoint para obtener los espacios de trabajo de los que tu cuenta es propietaria:
GET /v1/workspaces
Ejemplo de respuesta:
{
"data": [
{
"id": 1,
"name": "My Workspace",
"timezone": "America/New_York",
"default_comment_delay": null,
"enable_analytics": true
}
],
"pagination": {
"has_more": false,
"next_cursor": null,
"next": null
}
}
Utiliza el id devuelto como workspace_id en los endpoints específicos del espacio.
Todas las operaciones de espacios de trabajo requieren un plan Pro o Agency activo y solo se aplican a los espacios propiedad de la cuenta de la clave de API. Un espacio inexistente o perteneciente a otra cuenta devuelve 404 workspace_not_found.
Obtén un espacio de trabajo
GET /v1/workspaces/{workspace_id}
La respuesta es 200 OK con el objeto del espacio de trabajo:
{
"id": 1,
"name": "My Workspace",
"timezone": "America/New_York",
"default_comment_delay": null,
"enable_analytics": true
}
Crea un espacio de trabajo
POST /v1/workspaces
Ejemplo de solicitud:
{
"name": "My Workspace",
"timezone": "America/New_York",
"default_comment_delay": 5,
"enable_analytics": true
}
namees obligatorio, debe contener entre 1 y 30 caracteres y debe ser único entre tus espacios de trabajo.timezonees obligatorio y debe ser una zona horaria IANA válida, comoAmerica/New_York.default_comment_delayes opcional: un entero entre 0 y 120 minutos, onullpara no establecer un retraso predeterminado. Si se omite, su valor esnull.enable_analyticses opcional y su valor predeterminado estrue. No puede sernull.
Los campos no válidos devuelven 400 validation_failed. La creación también comprueba el límite de espacios de trabajo de tu plan activo. Si se alcanza el límite, la API devuelve 403 workspace_limit_reached, con el número permitido en details.limit.
Una solicitud correcta devuelve 201 Created, el objeto del espacio de trabajo y un encabezado Location con la URL del recurso. Social Inbox está desactivado en los espacios creados mediante la API pública. Su configuración no se expone en las solicitudes ni en las respuestas de la API.
Actualiza un espacio de trabajo
PATCH /v1/workspaces/{workspace_id}
Envía al menos uno de los cuatro campos admitidos e incluye solo los que quieras cambiar:
{
"name": "Renamed Workspace",
"default_comment_delay": null,
"enable_analytics": false
}
Los cuatro campos de creación son opcionales en una actualización; los campos omitidos conservan su valor. Se aplican las mismas reglas de validación. Un default_comment_delay: null explícito elimina el retraso predeterminado. Los campos name, timezone y enable_analytics no pueden ser null.
Cambiar la zona horaria recalcula los horarios de las colas, y cambiar enable_analytics actualiza la recopilación de datos analíticos igual que en el panel. Las actualizaciones conservan la configuración de Social Inbox. Una solicitud correcta devuelve 200 OK con el objeto actualizado del espacio de trabajo.
Elimina un espacio de trabajo
Eliminar un espacio de trabajo es una operación destructiva. Elimina el espacio y sus datos relacionados en Postoria, con la misma limpieza que al eliminarlo desde el panel. Los archivos almacenados y las analíticas se eliminan de forma asíncrona. Las publicaciones ya publicadas en redes sociales no se eliminan de esas redes.
DELETE /v1/workspaces/{workspace_id}?force=false
El parámetro de consulta opcional force tiene el valor predeterminado false. Por defecto, cualquier cuenta social que no se haya eliminado bloquea la eliminación del espacio, incluidas las cuentas que necesitan reconectarse. La API devuelve 409 workspace_has_social_accounts sin eliminar el espacio:
{
"error": {
"code": "workspace_has_social_accounts",
"message": "The workspace cannot be deleted while social accounts remain.",
"param": null,
"details": {
"social_account_ids": [123, 456],
"has_more": false
},
"request_id": "01JEXAMPLE"
}
}
El array social_account_ids contiene hasta 10 identificadores de cuentas que bloquean la operación; has_more es true si quedan más. Elimina primero esas cuentas u omite explícitamente esta comprobación:
DELETE /v1/workspaces/{workspace_id}?force=true
Con force=true, el espacio de trabajo y las cuentas que quedan se eliminan juntos. Este indicador solo omite la comprobación de cuentas: las comprobaciones de propiedad y del plan siguen aplicándose, y tu último espacio de trabajo no se puede eliminar ni siquiera con force=true (409 last_workspace).
Una eliminación correcta devuelve 204 No Content. Un espacio que no existe o ya se ha eliminado devuelve 404 workspace_not_found.
Conecta o reconecta cuentas sociales
La API pública utiliza un flujo OAuth interactivo para conectar nuevas cuentas sociales o renovar la autorización de las existentes. Tu aplicación inicia una autorización, dirige al usuario a la URL del proveedor y consulta el estado de la conexión después de que el proveedor lo redirija de vuelta a Postoria.
El mismo flujo de autorización puede devolver tanto cuentas nuevas como existentes:
connectable_accountscontiene las cuentas del proveedor que no están conectadas en el espacio de trabajo especificado.reconnectable_accountscontiene las cuentas existentes de ese espacio que pueden volver a autorizarse con la autorización OAuth obtenida.
Después de revisar estas listas, llama al endpoint de conexión con los PID del proveedor, al endpoint de reconexión con los ID de cuenta de Postoria o a ambos endpoints cuando corresponda.
Lista las opciones de conexión
Obtén las redes sociales y los métodos de autenticación disponibles actualmente mediante la API pública:
GET /v1/social-account-connection-options
Ejemplo de respuesta:
{
"data": [
{
"network": "facebook",
"auth_methods": [
"facebook_login",
"meta_business_portfolio"
]
},
{
"network": "instagram",
"auth_methods": [
"instagram_login",
"facebook_login",
"meta_business_portfolio"
]
}
],
"pagination": {
"has_more": false,
"next_cursor": null,
"next": null
}
}
No utilices el ejemplo de respuesta como una lista completa fija. Toma este endpoint como fuente de referencia, ya que las opciones compatibles pueden cambiar.
La versión inicial admite estas opciones:
| Red | Métodos de autenticación |
|---|---|
facebook | facebook_login, meta_business_portfolio |
instagram | instagram_login, facebook_login, meta_business_portfolio |
linkedin | linkedin_login |
tumblr | tumblr_login |
youtube | google_login |
pinterest | pinterest_login |
tiktok | tiktok_api_for_business |
google_business_profile | google_login |
threads | threads_login |
Inicia una autorización
Crea un estado de conexión para un espacio de trabajo:
POST /v1/workspaces/{workspace_id}/social-account-connections
Ejemplo de solicitud:
{
"network": "instagram",
"auth_method": "instagram_login"
}
Respuesta correcta (201 Created):
{
"state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
"is_completed": false,
"authorization_url": "https://www.instagram.com/oauth/authorize?...",
"expires_at": "2026-09-07T11:25:28.222872Z"
}
Abre authorization_url en un navegador para que el usuario complete el flujo del proveedor. Después, el proveedor redirige el navegador a la URL de callback alojada por Postoria, que registra el resultado de OAuth asociado a state. Tu aplicación no necesita proporcionar una URL de retorno ni llamar a un endpoint de finalización independiente.
El estado caduca una hora después de crearse. Inicia una autorización nueva si ya ha pasado expires_at. Si el estado ha caducado o está asociado a otro espacio de trabajo o cuenta de Postoria, la API devuelve 404 social_account_connection_not_found.
Consulta el resultado de la autorización
Cuando el usuario haya completado el flujo del proveedor, consulta el estado de la conexión:
GET /v1/workspaces/{workspace_id}/social-account-connections/{state}
Puedes consultar periódicamente este endpoint mientras is_completed sea false. Este campo indica que Postoria todavía no ha recibido y almacenado el callback de OAuth; no significa que las cuentas ya se hayan conectado o reconectado.
Ejemplo de respuesta tras completar la autorización:
{
"state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
"is_completed": true,
"expires_at": "2026-09-07T11:25:28.222872Z",
"network": "instagram",
"auth_method": "instagram_login",
"error": null,
"connectable_accounts": [
{
"pid": "17841400000000001",
"name": "Postoria Demo",
"username": "postoria.demo",
"description": "Demo account",
"url": "https://www.instagram.com/postoria.demo/",
"logo_url": "https://example.com/profile.jpg",
"account_category": "profile"
}
],
"reconnectable_accounts": [
{
"account_id": 123,
"pid": "17841400000000002",
"name": "Postoria",
"username": "postoria.app",
"description": "Postoria",
"url": "https://www.instagram.com/postoria.app/",
"logo_url": "https://example.com/profile-2.jpg",
"account_category": "profile"
}
]
}
Si is_completed es true y error no es null, el proceso de autorización del proveedor ha fallado o el usuario lo ha rechazado. No llames a ninguno de los endpoints que modifican cuentas; muestra el error o inicia una autorización nueva.
Conecta cuentas nuevas
Selecciona uno o varios PID exactamente como aparecen en connectable_accounts:
POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts
Ejemplo de solicitud:
{
"pids": [
"17841400000000001"
]
}
La validación de la solicitud falla si un PID no está disponible mediante esta autorización o ya está conectado en el espacio de trabajo.
Reconecta cuentas existentes
Selecciona uno o varios ID de cuenta de Postoria exactamente como aparecen en reconnectable_accounts:
POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect
Ejemplo de solicitud:
{
"account_ids": [123, 456]
}
Cada cuenta solicitada debe pertenecer al espacio de trabajo especificado y a la red seleccionada, y la autorización OAuth obtenida debe proporcionar acceso a ella. Si alguna cuenta solicitada no está disponible, la API devuelve 400 social_accounts_not_available antes de reconectar las cuentas seleccionadas.
Una cuenta existente puede reconectarse mediante cualquier método de autenticación admitido actualmente para su red; no tiene que coincidir con el método utilizado para la conexión original. Selecciona siempre el account_id devuelto en lugar de intentar determinar la correspondencia por tu cuenta.
Respuesta de las operaciones sobre cuentas
Tanto el endpoint de conexión como el de reconexión devuelven las cuentas de Postoria afectadas:
{
"state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
"accounts": [
{
"id": 123,
"name": "Postoria",
"custom_name": "Channel 113",
"description": "postoria.app",
"network": "instagram",
"url": "https://www.instagram.com/postoria.app/",
"metadata": {
"channel_number": "113"
}
}
]
}
Lista las cuentas sociales
Utiliza este endpoint para obtener las cuentas conectadas de un espacio de trabajo:
GET /v1/workspaces/{workspace_id}/social-accounts
Ejemplo de respuesta:
{
"data": [
{
"id": 123,
"name": "Postoria",
"custom_name": "Channel 113",
"description": "postoria.app",
"network": "instagram",
"url": "https://www.instagram.com/postoria.app",
"metadata": {
"channel_number": "113",
"owner_account": "acme-media"
}
}
],
"pagination": {
"has_more": false,
"next_cursor": null,
"next": null
}
}
name es el nombre de la cuenta recibido de la red social. custom_name es un nombre opcional configurado en Postoria. metadata es un objeto opcional que contiene claves y valores de texto controlados por tu integración. Las claves de los metadatos conservan el uso original de mayúsculas y minúsculas.
Utiliza los ID devueltos en social_account_ids al crear publicaciones. También puedes utilizar los metadatos para asociar cada cuenta conectada con un identificador estable de tu propio sistema.
Actualiza una cuenta social
Utiliza este endpoint para establecer o actualizar el nombre personalizado y los metadatos de una cuenta social conectada:
PATCH /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
Ejemplo de solicitud:
{
"custom_name": "Channel 113",
"metadata": {
"channel_number": "113",
"owner_account": "acme-media",
"group": "north-america"
}
}
Ambos campos son opcionales, pero la solicitud debe incluir al menos uno. Los campos omitidos no se modifican.
Comportamiento importante:
- Los espacios al principio y al final de
custom_namese eliminan antes de almacenarlo; el nombre puede contener hasta 255 caracteres. - Establece
custom_nameennullo en una cadena vacía para dejar de utilizar el nombre personalizado en la interfaz de Postoria. metadatadebe ser un objeto JSON que contenga claves y valores de texto.- Los metadatos pueden contener hasta 50 entradas. Las claves pueden contener hasta 64 caracteres y los valores, hasta 1.024 caracteres.
- Al enviar
metadata, se reemplaza el objeto de metadatos completo; las claves individuales no se combinan con las existentes. - Establece
metadataennullpara borrar todos los metadatos o en{}para conservar un objeto de metadatos vacío. - Los nombres personalizados y los metadatos permanecen asociados a la cuenta social de Postoria cuando esta se reconecta o se vuelve a autorizar.
Respuesta correcta:
{
"id": 123,
"name": "Postoria",
"custom_name": "Channel 113",
"description": "postoria.app",
"network": "instagram",
"url": "https://www.instagram.com/postoria.app",
"metadata": {
"channel_number": "113",
"owner_account": "acme-media",
"group": "north-america"
}
}
Si la cuenta social no existe en el espacio de trabajo especificado, la API devuelve 404 social_account_not_found.
Elimina una cuenta social
Utiliza este endpoint para eliminar una cuenta social conectada de un espacio de trabajo:
DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
El parámetro de consulta force es opcional y su valor predeterminado es false. De forma predeterminada, la cuenta no se puede eliminar mientras esté asociada a publicaciones con el estado scheduled o queued. Los borradores no bloquean la eliminación.
Si quedan publicaciones programadas o en cola, la API devuelve 409 social_account_has_scheduled_posts sin modificar la cuenta ni las publicaciones asociadas:
{
"error": {
"code": "social_account_has_scheduled_posts",
"message": "The social account cannot be deleted while scheduled or queued posts remain.",
"param": null,
"details": {
"post_ids": [3001, 3002],
"has_more": false
},
"request_id": "01JEXAMPLE"
}
}
post_ids incluye hasta 10 identificadores de publicaciones que bloquean la operación. Si hay más publicaciones que bloquean la eliminación, has_more es true.
Para eliminar la cuenta aunque queden publicaciones programadas o en cola, establece force=true:
DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}?force=true
Cuando se elimina la cuenta, Postoria aplica la misma lógica de limpieza que al hacerlo desde el panel. La cuenta se desvincula de los borradores y de las publicaciones programadas o en cola, así como de las automatizaciones asociadas. También pueden eliminarse las publicaciones que se queden sin cuentas sociales.
La eliminación desconecta la cuenta del espacio de trabajo de Postoria, pero no revoca la autorización en la red social. Si la operación se completa correctamente, la API devuelve 204 No Content. Si la cuenta social no existe en el espacio especificado o ya se eliminó, la API devuelve 404 social_account_not_found.
Lista las colas
Utiliza este endpoint para obtener las colas de un espacio de trabajo:
GET /v1/workspaces/{workspace_id}/queues
Ejemplo de respuesta:
{
"data": [
{
"id": 456,
"name": "Morning posts",
"is_paused": false
}
],
"pagination": {
"has_more": false,
"next_cursor": null,
"next": null
}
}
Utiliza el ID de cola devuelto cuando crees una publicación con publish_mode establecido en queue.
Sube recursos multimedia
Hay dos formas de añadir recursos mediante la API:
- Crear una URL de carga y subir el archivo por tu cuenta.
- Importar el recurso desde una URL HTTPS pública.
Ambos métodos crean un objeto multimedia. Utiliza el endpoint de estado para comprobar cuándo está listo.
El elemento debe tener status igual a ready antes de poder incluirlo al crear una publicación.
Hay dos formas de proporcionar una miniatura para un vídeo:
- Miniatura personalizada: carga o importa un archivo de imagen mediante los endpoints de contenido multimedia. Cuando el elemento multimedia de imagen tenga el estado
ready, pasa su ID comothumbnail_media_idpara el vídeo enPOST /posts. - Miniatura generada a partir de un fotograma del vídeo: incluye
thumbnail_timestamp_msal crear una carga o importación mediante URL de un vídeo. El valor se mide en milisegundos. Postoria crea un elemento multimedia de imagen independiente y devuelve su ID comothumbnail_media_id. Espera hasta que tanto el vídeo como la imagen generada tengan el estadoreadyy luego pasa ese ID enPOST /posts.
Los tipos compatibles incluyen formatos habituales de imagen, vídeo y documentos, como JPEG, PNG, WebP, GIF, MP4, MOV y PDF.
Límites de tamaño de los archivos multimedia
Antes de subir un archivo, comprueba tanto el límite de carga o importación como el de la red social y el formato de publicación. Estos son los límites de Postoria. Todos los tamaños máximos indicados a continuación se aplican por archivo, no al tamaño total de una publicación, e incluyen el valor indicado: un archivo cuyo tamaño sea exactamente el máximo es aceptado por la comprobación de tamaño.
Utiliza los valores exactos en bytes de las tablas siguientes para comprobar el tamaño de los archivos.
Límites de carga e importación mediante URL
Estos límites se aplican al archivo de origen tanto para las URL de carga como para las importaciones mediante URL. El tamaño del archivo se comprueba durante el procesamiento del recurso multimedia.
| Tipo de recurso | Tamaño máximo del archivo |
|---|---|
| Imágenes: JPG/JPEG, PNG, WebP, GIF | 20 MiB (20.971.520 bytes) |
| Vídeos: MP4, MOV | 5 GiB (5.368.709.120 bytes) |
| Documentos: PDF | 100 MiB (104.857.600 bytes) |
Completar una carga o recibir status: ready no garantiza que el recurso pueda utilizarse en una publicación. Cuando creas una publicación, Postoria también comprueba el recurso almacenado según la red social y el formato seleccionados. Un archivo puede superar el procesamiento multimedia y aun así exceder un límite de publicación.
Límites de publicación por red social
La tabla muestra el máximo efectivo para los nuevos recursos añadidos mediante la API, teniendo en cuenta tanto los límites de carga o importación como los de publicación. Se aplica a los archivos adjuntos principales de la publicación (media[].media_id). Las imágenes son archivos JPG/JPEG, PNG y WebP; los vídeos son archivos MP4 y MOV. Los formatos GIF y PDF se indican por separado donde son compatibles. Los formatos multimedia que no figuran para una red social no se admiten como recursos de una publicación.
| Red social | Recurso / formato de publicación | Tamaño máximo del archivo |
|---|---|---|
| Imágenes: feed, carrusel, Story | 8 MiB (8.388.608 bytes) | |
| Vídeos: feed, Reel, Story | 1 GiB (1.073.741.824 bytes) | |
| Imágenes: feed, carrusel, Story | 8 MiB (8.388.608 bytes) | |
| Vídeos: feed, carrusel, Reel | 1 GiB (1.073.741.824 bytes) | |
| Vídeos: Story | 100 MiB (104.857.600 bytes) | |
| X | Imágenes | 5 MiB (5.242.880 bytes) |
| X | GIF | 15 MiB (15.728.640 bytes) |
| X | Vídeos | 512 MiB (536.870.912 bytes) |
| Imágenes y GIF | 20 MiB (20.971.520 bytes) | |
| Vídeos | 5 GiB (5.368.709.120 bytes) | |
| 100 MiB (104.857.600 bytes) | ||
| Imágenes | 20 MiB (20.971.520 bytes) | |
| Vídeos | 2 GiB (2.147.483.648 bytes) | |
| YouTube | Vídeos | 5 GiB (5.368.709.120 bytes) |
| TikTok | Imágenes | 20 MiB (20.971.520 bytes) |
| TikTok | Vídeos | 4 GiB (4.294.967.296 bytes) |
| Google Business Profile | Imágenes | 15 MiB (15.728.640 bytes) |
| Telegram | Imágenes y GIF | 10 MiB (10.485.760 bytes) |
| Telegram | Vídeos | 50 MiB (52.428.800 bytes) |
| Threads | Imágenes | 8 MiB (8.388.608 bytes) |
| Threads | Vídeos | 1 GiB (1.073.741.824 bytes) |
| Tumblr | Imágenes | 20 MiB (20.971.520 bytes) |
| Tumblr | GIF | 10 MiB (10.485.760 bytes) |
| Tumblr | Vídeos | 500 MiB (524.288.000 bytes) |
| Bluesky | Imágenes | 1 MB (1.000.000 bytes) |
| Bluesky | Vídeos | 50 MB (50.000.000 bytes) |
- Los mismos límites por archivo se aplican a los carruseles cuando la red social admite ese tipo de recurso.
- Cuando
facebook.also_publish_media_to_storiesoinstagram.also_publish_media_to_storiesestá activado, el recurso también debe cumplir el límite de Story correspondiente. Para los vídeos de Instagram, esto supone un máximo de 100 MiB (104.857.600 bytes). - Al publicar el mismo recurso en varias redes sociales o formatos, utiliza el límite más estricto que corresponda.
Sube un archivo mediante una URL de carga
Primero, crea una carga:
POST /v1/workspaces/{workspace_id}/media/uploads
Solicitud:
{
"name": "image.jpg",
"content_type": "image/jpeg"
}
Ejemplo de respuesta:
{
"id": 9001,
"status": "waiting_for_upload",
"upload": {
"url": "https://temporary-upload-url.example"
}
}
Para generar una miniatura en una carga directa de vídeo, incluye la marca de tiempo opcional al crear la carga:
{
"name": "video.mp4",
"content_type": "video/mp4",
"thumbnail_timestamp_ms": 5000
}
La respuesta 201 Created contiene el ID del elemento multimedia de la miniatura generada antes de que termine el procesamiento de los archivos:
{
"id": 9002,
"status": "waiting_for_upload",
"thumbnail_media_id": 9003,
"upload": {
"url": "https://temporary-upload-url.example"
}
}
Sube los bytes del archivo a la upload.url devuelta mediante una solicitud HTTP PUT. Envía los bytes sin procesar como cuerpo de la solicitud y utiliza el mismo valor de content_type que al crear la carga.
Ejemplo:
curl -X PUT "https://temporary-upload-url.example" \
-H "Content-Type: image/jpeg" \
--data-binary "@image.jpg"
La URL de carga es temporal. Si caduca antes de subir y completar el elemento, crea una nueva carga.
Después de subir el archivo, completa la carga:
POST /v1/workspaces/{workspace_id}/media/{media_id}/complete
Ejemplo de respuesta:
{
"id": 9001,
"status": "processing",
"file_id": null,
"error_code": null,
"error_message": null
}
Postoria procesará el recurso en segundo plano.
Importa un recurso desde una URL
Utiliza este endpoint cuando el archivo ya esté disponible en una URL HTTPS pública:
POST /v1/workspaces/{workspace_id}/media/imports
Solicitud:
{
"url": "https://example.com/video.mp4",
"thumbnail_timestamp_ms": 5000
}
Ejemplo de respuesta:
{
"id": 9002,
"status": "processing",
"file_id": null,
"thumbnail_media_id": 9003,
"error_code": null,
"error_message": null
}
Solo se admiten URL HTTPS públicas. No se admiten URL privadas o autenticadas, archivos locales ni rutas relativas.
En este ejemplo, el elemento multimedia 9002 es el vídeo y el elemento 9003 es la miniatura generada. Consulta ambos elementos hasta que estén listos. El vídeo de origen contiene thumbnail_media_id, mientras que la miniatura generada contiene el thumbnail_timestamp_ms solicitado.
El mismo campo opcional puede incluirse al crear una carga directa de vídeo. Solo es válido para vídeos y debe ser igual o superior a cero.
Comprueba el estado de un recurso
Utiliza este endpoint para comprobar si un elemento está listo:
GET /v1/workspaces/{workspace_id}/media/{media_id}
Ejemplo de respuesta cuando está listo:
{
"id": 9001,
"status": "ready",
"file_id": 701,
"error_code": null,
"error_message": null
}
Ejemplo de respuesta para una miniatura generada:
{
"id": 9003,
"status": "ready",
"file_id": 702,
"thumbnail_timestamp_ms": 5000,
"error_code": null,
"error_message": null
}
Ejemplo de respuesta con error:
{
"id": 9001,
"status": "failed",
"file_id": null,
"error_code": "media_processing_failed",
"error_message": "The file format is not supported."
}
Estados posibles:
waiting_for_uploadprocessingreadyfailed
Crea una publicación
Utiliza este endpoint para crear una publicación:
POST /v1/workspaces/{workspace_id}/posts
La API no crea borradores. La publicación se crea con uno de estos modos:
publish_nowschedulequeue
scheduled_time solo es obligatorio para schedule. queue_id solo es obligatorio para queue. No debes enviar ninguno de los dos campos con publish_now.
Todas las cuentas sociales seleccionadas deben admitir el tipo de contenido elegido; de lo contrario, se rechaza la solicitud.
Ejemplo de solicitud programada:
{
"publish_mode": "schedule",
"social_account_ids": [123],
"content_type": "image",
"media": [
{
"media_id": 9001
}
],
"caption": "Post caption",
"first_comment": "More details in the first comment.",
"comment_delay": 5,
"is_ai_generated": true,
"scheduled_time": "2026-06-01T10:00:00Z"
}
Ejemplo de respuesta:
{
"id": 3001,
"status": "scheduled",
"date": "2026-06-01T10:00:00Z",
"queue_id": null,
"is_ai_generated": true,
"results": [
{
"account_id": 123,
"link_to_post": null,
"error": null
}
],
"instagram": {
"content": "image",
"caption": "Post caption",
"files": [
{
"url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
}
],
"comment": "More details in the first comment.",
"comment_delay": 5
}
}
Las respuestas incluyen un objeto por cada red social activada, como facebook, instagram, linkedin, youtube o tiktok. Cada objeto de red contiene:
content: el tipo de contenido efectivo para esa red.caption: el texto utilizado para esa red.files: los archivos multimedia de esa red. Las URL son enlaces firmados temporales que pueden abrirse sin autenticación durante aproximadamente una hora. Un vídeo también puede incluirthumbnail_urlsi hay una miniatura disponible.thumbnail_timestamp_mssolo se incluye cuando la miniatura se generó a partir de un fotograma del vídeo.
Ejemplo de archivo de vídeo con una miniatura generada:
{
"url": "https://assets.postoria.io/w/1/video.mp4?st=temporary_signed_token",
"thumbnail_url": "https://assets.postoria.io/w/1/thumbnail.png?st=temporary_signed_token",
"thumbnail_timestamp_ms": 5000
}
Según la red y el tipo de contenido, el objeto también puede incluir comment y comment_delay, link u opciones de publicación específicas. comment_delay se expresa en minutos. Las publicaciones con enlaces y los primeros comentarios solo están disponibles donde la red y el tipo de contenido los admiten. Las historias no admiten primeros comentarios.
Cuando están disponibles, los resultados de publicación se devuelven por cuenta en results. En publicaciones programadas o en cola, puede que no haya resultados hasta que se procese la publicación. Una publicación puede incluir resultados correctos y fallidos para distintas cuentas.
Divulgación de contenido generado por IA
Establece el campo de nivel superior is_ai_generated en true cuando la publicación deba llevar la indicación de contenido generado por IA de las redes sociales compatibles.
{
"is_ai_generated": true
}
Postoria envía la indicación correspondiente cuando el destino y el tipo de contenido son compatibles:
- Cuentas de Instagram
- Publicaciones de vídeo de TikTok
- Vídeos de YouTube
- Publicaciones de X
- Pines de Pinterest
El ajuste no se envía para publicaciones de fotos de TikTok. Los destinos y tipos de contenido no compatibles lo ignoran.
Campos de fecha y hora
Los campos de fecha y hora utilizan cadenas ISO 8601 en UTC.
Ejemplo:
"scheduled_time": "2026-06-01T10:00:00Z"
Utiliza UTC e incluye la Z final.
Si programas a partir de una hora local, conviértela a UTC antes de enviarla a la API.
Publica inmediatamente
Establece publish_mode en publish_now.
{
"publish_mode": "publish_now",
"social_account_ids": [123],
"content_type": "image",
"media": [
{
"media_id": 9001
}
],
"caption": "Publishing from Postoria Public API"
}
Programa una publicación
Establece publish_mode en schedule e incluye scheduled_time.
{
"publish_mode": "schedule",
"social_account_ids": [123],
"content_type": "image",
"media": [
{
"media_id": 9001
}
],
"caption": "Scheduled from Postoria Public API",
"scheduled_time": "2026-06-01T10:00:00Z"
}
scheduled_time debe ser una fecha futura.
Añade una publicación a una cola
Establece publish_mode en queue e incluye queue_id.
{
"publish_mode": "queue",
"social_account_ids": [123],
"content_type": "image",
"media": [
{
"media_id": 9001
}
],
"caption": "Queued from Postoria Public API",
"queue_id": 456
}
La cola debe pertenecer al mismo espacio de trabajo.
Tipos de contenido
Valores compatibles de content_type:
textimagevideodocumentcarousellinkstoryreel
Si no proporcionas content_type, Postoria intenta determinarlo a partir de los datos:
- Varios elementos multimedia →
carousel - Un elemento multimedia → el tipo correspondiente, como
image,videoodocument - Una URL sin recursos multimedia →
link - Solo texto →
text
Siguen aplicándose las reglas específicas de cada red. Todas las cuentas seleccionadas deben admitir el tipo solicitado; de lo contrario, la API devuelve un error de validación y no crea la publicación.
Añade recursos multimedia a una publicación
Utiliza el array media para hacer referencia a elementos creados mediante los endpoints de carga o importación. Cada elemento debe tener status igual a ready.
Antes de adjuntar recursos, comprueba los límites de tamaño de los archivos multimedia para cada red social y formato de publicación seleccionados. Un recurso listo puede seguir excediendo un límite de publicación.
{
"media": [
{
"media_id": 9001
}
]
}
En un vídeo puedes proporcionar opcionalmente una miniatura. thumbnail_media_id pertenece al media_id correspondiente y debe hacer referencia a una imagen lista.
- Para una miniatura personalizada, carga o importa el archivo de imagen mediante los endpoints de contenido multimedia y utiliza su ID.
- Para una miniatura generada a partir de un fotograma del vídeo, envía
thumbnail_timestamp_msal crear la carga o importación del vídeo y utiliza elthumbnail_media_iddevuelto cuando tenga el estadoready.
En ambos casos, POST /posts recibe thumbnail_media_id. La marca de tiempo solo se proporciona al crear el elemento multimedia de vídeo, no al crear la publicación.
{
"media": [
{
"media_id": 9002,
"thumbnail_media_id": 9003
}
]
}
Publicaciones con enlaces
En publicaciones de tipo link, incluye link_url:
{
"publish_mode": "schedule",
"social_account_ids": [123],
"content_type": "link",
"caption": "Useful link",
"link_url": "https://example.com/article",
"scheduled_time": "2026-06-01T10:00:00Z"
}
Postoria importará la información del enlace al crear la publicación.
Primer comentario
Utiliza first_comment para añadir un primer comentario en las redes que lo admitan. Utiliza comment_delay para retrasarlo; el valor se expresa en minutos.
{
"first_comment": "More details in the first comment."
}
Siguen aplicándose las reglas específicas de cada red. Los campos de respuesta del primer comentario solo se devuelven en las redes compatibles.
Opciones de Facebook
Utiliza el objeto facebook para las opciones específicas de Facebook:
{
"facebook": {
"location_id": "12345678901234567890",
"also_publish_media_to_stories": true
}
}
location_id es opcional y debe ser una cadena de entre 1 y 64 dígitos que represente un número mayor que cero. Identifica la página de Facebook correspondiente a la ubicación física que Meta debe asociar con la publicación. Envía el ID como una cadena JSON, no como un número, para evitar que los identificadores largos pierdan precisión.
Cuando also_publish_media_to_stories es true, Postoria crea primero la publicación normal y después publica cada archivo adjunto como una historia de Facebook independiente. La opción no tiene efecto cuando content_type es story o link.
Opciones de Instagram
Utiliza el objeto instagram para las opciones específicas de Instagram:
{
"instagram": {
"location_id": "12345678901234567890",
"also_publish_media_to_stories": true,
"collaborators": ["creator_one"],
"publish_as_trial_reel": false,
"auto_share_if_performs_well": false,
"user_tags": [
{
"media_id": 9001,
"username": "creator_one",
"x": 0.5,
"y": 0.5
}
]
}
}
location_id es opcional y debe tener el mismo formato que la opción de Facebook: una cadena de entre 1 y 64 dígitos que represente un número mayor que cero. Debe corresponder a una página de Facebook asociada a una ubicación física.
Cuando also_publish_media_to_stories es true, Postoria crea primero la publicación normal y después publica cada archivo adjunto como una historia de Instagram independiente. La opción no tiene efecto cuando content_type es story.
user_tags.media_id debe hacer referencia a un recurso adjunto a la misma publicación. En las respuestas, las etiquetas de usuario utilizan file_id en lugar de media_id.
Opciones de Pinterest
Utiliza el objeto pinterest para las opciones específicas de Pinterest:
{
"pinterest": {
"title": "Pin title",
"website": "https://example.com/article",
"alt_text": "A description of the image"
}
}
website es la URL de destino del Pin.
Opciones de Google Business Profile
Utiliza el objeto google_business_profile para añadir un botón de acción:
{
"google_business_profile": {
"button_type": "LEARN_MORE",
"button_url": "https://example.com"
}
}
Los tipos compatibles son BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP y CALL. Se requiere una URL en todos salvo CALL.
Ajustes de republicación
Utiliza repost para configurar la republicación.
Ejemplo:
{
"repost": {
"frequency": "do_not_repeat",
"until": null
}
}
Si configuras una frecuencia, until debe ser una fecha y hora UTC futura cuando lo exijan los ajustes seleccionados.
Opciones de YouTube
Utiliza el objeto youtube al crear publicaciones para cuentas de YouTube.
Ejemplo:
{
"youtube": {
"title": "Video title",
"visibility": "public",
"category": "People & Blogs",
"made_for_kids": false,
"video_language": "en",
"recording_date": "2026-06-01T00:00:00Z",
"tags": ["tag1", "tag2"]
}
}
Utiliza los campos de YouTube solo cuando al menos una cuenta seleccionada sea de YouTube.
Para consultar los valores compatibles, revisa la documentación de la carga en lote: Cómo cargar publicaciones de forma masiva con un archivo CSV en Postoria.
Opciones de TikTok
Utiliza el objeto tiktok al crear publicaciones para cuentas de TikTok.
Ejemplo:
{
"tiktok": {
"who_can_watch": "public",
"allow_comments": true,
"allow_duet": false,
"allow_stitch": false,
"disclose_post_content": false,
"your_brand": false,
"branded_content": false,
"photo_title": "Photo title",
"auto_add_music": false
}
}
Campos compatibles de TikTok:
who_can_watch:public,followers,friendsoprivateallow_comments:trueofalseallow_duet:trueofalseallow_stitch:trueofalsedisclose_post_content:trueofalseyour_brand:trueofalsebranded_content:trueofalsephoto_title: texto sin formato de hasta 90 caracteresauto_add_music:trueofalse
Utiliza los campos de TikTok solo cuando al menos una cuenta seleccionada sea de TikTok.
Opciones de Tumblr
Utiliza el objeto tumblr para adjuntar etiquetas nativas de Tumblr separadas del texto:
{
"caption": "Explore our latest indie game",
"tumblr": {
"tags": ["gaming", "indiegame", "steam", "hades2"]
}
}
Postoria admite hasta 30 etiquetas de Tumblr. Elimina el espacio alrededor y un # inicial, ignora valores vacíos y elimina duplicados sin distinguir mayúsculas y minúsculas. Un elemento del array no puede contener una coma ni comillas dobles. Utiliza estas opciones solo cuando al menos una cuenta seleccionada sea de Tumblr.
Lista publicaciones
Utiliza este endpoint para listar las publicaciones de un espacio:
GET /v1/workspaces/{workspace_id}/posts
Parámetros de consulta opcionales:
account_ids: ID de cuentas sociales. Repite el parámetro o utiliza valores separados por comas.queue_id: ID de cola.status: uno dedraft,scheduled,in_progress,postedoqueued.networks: uno o varios valores de red, comoinstagram,facebook,linkedin,youtubeotiktok.date_from: fecha y hora programada igual o posterior a este valor UTC.date_to: fecha y hora programada anterior a este valor UTC.limit: número de publicaciones que se devolverán. El valor predeterminado es25y el máximo es100.cursor: cursor de paginación devuelto por la página anterior.
account_ids y queue_id deben pertenecer al espacio especificado.
Ejemplo de solicitud:
curl "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25" \
-H "Authorization: Bearer pst_live_your_api_key"
Ejemplo de respuesta:
{
"data": [
{
"id": 3001,
"status": "scheduled",
"date": "2026-06-01T10:00:00Z",
"queue_id": null,
"is_ai_generated": true,
"results": [
{
"account_id": 123,
"link_to_post": null,
"error": null
}
],
"instagram": {
"caption": "Scheduled post caption",
"files": [
{
"url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
}
]
}
}
],
"pagination": {
"has_more": true,
"next_cursor": "eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0",
"next": "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0"
}
}
Para solicitar la página siguiente, llama directamente a next o vuelve a enviar next_cursor como cursor:
GET /v1/workspaces/{workspace_id}/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0
Comprueba el estado de una publicación
Utiliza este endpoint para consultar el estado:
GET /v1/workspaces/{workspace_id}/posts/{post_id}
date es la hora de publicación programada. Puede ser null en publicaciones en cola o inmediatas.
Ejemplo de respuesta:
{
"id": 3001,
"status": "posted",
"date": "2026-06-01T10:00:00Z",
"queue_id": null,
"is_ai_generated": true,
"results": [
{
"account_id": 123,
"link_to_post": "https://www.instagram.com/p/example",
"error": null
}
],
"instagram": {
"caption": "Published post caption",
"files": [
{
"url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
}
]
}
}
Estados posibles:
draftscheduledin_progresspostedqueued
Significado de los elementos de resultado:
link_to_postcontiene un valor cuando la publicación se ha publicado correctamente y hay un enlace público disponible.errorcontiene un valor cuando ha fallado la publicación para esa cuenta.- Tanto
link_to_postcomoerrorpueden sernullantes de que se publique.
Elimina una publicación
Utiliza este endpoint para eliminarla:
DELETE /v1/workspaces/{workspace_id}/posts/{post_id}
Respuesta correcta:
204 No Content
La publicación debe pertenecer al espacio especificado.
Al eliminarla, desaparece de Postoria. Esto no elimina contenido que ya se haya publicado en las redes sociales. Si la publicación ya ha comenzado, eliminarla de Postoria no detiene el proceso. Los resultados de las cuentas se eliminan junto con la publicación y no pueden recuperarse después.
Obtén analíticas de publicaciones concretas
Utiliza este endpoint para obtener las analíticas disponibles más recientes de entre uno y 100 ID de publicaciones de Postoria:
GET /v1/workspaces/{workspace_id}/analytics/posts?post_ids=3001&post_ids=3002
Repite post_ids para cada publicación. Los ID deben ser números enteros positivos. Se aceptan duplicados y se tratan como un único ID.
Todas las publicaciones solicitadas deben pertenecer al espacio. Si falta alguna o pertenece a otro espacio, toda la solicitud falla con 404 post_not_found; la respuesta no identifica qué ID ha fallado.
La respuesta contiene una fila por cada publicación en una cuenta social asociada a las publicaciones solicitadas. Las métricas se representan como pares nombre/valor porque su disponibilidad varía según la red y puede cambiar con el tiempo:
{
"data": [
{
"post_id": 3001,
"social_account_id": 123,
"network": "tiktok",
"content_type": "video",
"published_at": "2026-08-01T10:00:00Z",
"analytics_refreshed_at": "2026-08-25T12:34:56Z",
"metrics": [
{ "name": "views", "value": 1250 },
{ "name": "likes", "value": 84 }
]
}
],
"pagination": {
"has_more": false,
"next_cursor": null,
"next": null
}
}
Las métricas no disponibles se omiten. Si se sabe que el valor de una métrica es cero, se devuelve cero. analytics_refreshed_at indica la fecha y hora, en formato ISO 8601 y UTC, de la última vez que Postoria obtuvo correctamente las analíticas de la publicación de la red social. Si la publicación existe pero sus analíticas aún no están disponibles, analytics_refreshed_at es null y metrics es un array vacío.
Los valores de red utilizan identificadores canónicos, como linkedin, youtube, tiktok y google_business_profile.
Las métricas de YouTube utilizan nombres diferenciados con el prefijo you_tube_. Algunos ejemplos son you_tube_views, you_tube_engaged_views, you_tube_likes, you_tube_dislikes, you_tube_estimated_minutes_watched, you_tube_average_view_duration y you_tube_subscribers_gained. El endpoint puede devolver tanto métricas aditivas como promedios o tasas no aditivas.
Obtén un resumen agregado del rendimiento
Utiliza este endpoint para agregar las métricas disponibles más recientes del contenido publicado durante un intervalo UTC:
GET /v1/workspaces/{workspace_id}/analytics/post-performance/summary?published_from=2026-08-01T00:00:00Z&published_to=2026-09-01T00:00:00Z&granularity=day&group_by=network
Parámetros de consulta obligatorios:
published_from: marca de tiempo UTC ISO 8601 inclusiva conZo+00:00.published_to: marca de tiempo UTC ISO 8601 exclusiva conZo+00:00.
El intervalo debe ser superior a cero y no puede superar 366 días.
Parámetros opcionales:
granularity:hour,day,monthoyear. Omítelo para no devolver intervalos temporales de publicación.group_by:network,content_typeosocial_account. Omítelo para no utilizar una dimensión adicional de agrupación.
granularity y group_by son independientes. Por ejemplo, puedes agrupar por red sin intervalos de tiempo, utilizar intervalos diarios sin agrupar por una dimensión, combinar ambos u omitirlos para obtener una sola fila total.
Cuando está presente granularity, los intervalos utilizan la zona horaria del espacio. La respuesta incluye esa zona IANA y un published_period por fila. start y end son instantes UTC, end es exclusivo y key es la etiqueta correspondiente en la hora local del espacio.
{
"data": [
{
"published_period": {
"start": "2026-08-01T04:00:00Z",
"end": "2026-08-02T04:00:00Z",
"key": "2026-08-01"
},
"network": "linkedin",
"post_count": 3,
"metrics": [
{ "name": "views", "value": 4200 },
{ "name": "comments", "value": 17 }
]
}
],
"timezone": "America/New_York"
}
Si se omite granularity, también se omiten published_period y el campo superior timezone. Si se omite group_by, no se devuelve ningún campo de agrupación. En caso contrario, cada fila contiene exactamente uno de estos campos: network, content_type o social_account_id.
El resumen agrupa las publicaciones según el momento en que salieron. Suma sus métricas disponibles más recientes; no muestra cuándo se produjeron las visualizaciones, reacciones u otras interacciones. Los totales cero y las métricas no disponibles se omiten. Las métricas no aditivas, como video_skip_rate, video_average_watch_time_milliseconds, los promedios de YouTube y las tasas de YouTube, no se incluyen porque no se pueden sumar correctamente.
Obtén analíticas diarias de cuentas
Obtén las métricas diarias almacenadas de las cuentas sociales de un espacio de trabajo:
GET /v1/workspaces/{workspace_id}/analytics/accounts?date_from=2026-08-01&date_to=2026-09-01&social_account_ids=123
Ambos endpoints de cuentas requieren estos parámetros:
date_from: fecha de calendario inicial inclusiva en formatoYYYY-MM-DD.date_to: fecha de calendario final exclusiva en formatoYYYY-MM-DD.
El intervalo debe ser mayor que cero y no puede superar los 366 días. Las fechas son las almacenadas para las analíticas de origen, sin conversión a la zona horaria del espacio de trabajo. No hay datos por hora.
Ambos endpoints admiten estos filtros opcionales:
social_account_ids: repite el parámetro para cada cuenta. Se permiten hasta 100 identificadores positivos distintos; los duplicados cuentan una sola vez.networks: repite el parámetro para cada identificador canónico de red, comoinstagram,linkedinoyoutube.
Sin filtros, se seleccionan todas las cuentas actuales del espacio de trabajo. Con ambos filtros, las cuentas deben cumplir los dos. Cada identificador solicitado debe pertenecer al espacio de trabajo; de lo contrario, toda la solicitud falla con 404 social_account_not_found. Los parámetros no válidos devuelven 400.
Los resultados diarios admiten limit (valor predeterminado y máximo: 100) y cursor. Cada fila representa una cuenta y una fecha. Sigue la URL completa de pagination.next o envía pagination.next_cursor como cursor mientras pagination.has_more sea verdadero.
{
"data": [
{
"social_account_id": 123,
"network": "instagram",
"analytics_date": "2026-08-01",
"analytics_refreshed_at": "2026-08-02T12:34:56Z",
"metrics": [
{ "name": "followers", "value": 1500 },
{ "name": "views", "value": 4200 }
]
}
],
"pagination": {
"has_more": false,
"next_cursor": null,
"next": null
}
}
Los nombres de las métricas utilizan snake_case, con nombres diferenciados con el prefijo you_tube_ para YouTube. Las métricas no disponibles se omiten; los ceros conocidos se conservan. Los resultados diarios incluyen las medias, tasas y valoraciones originales disponibles. analytics_refreshed_at es la fecha y hora UTC ISO 8601 de actualización de la fila de origen. Si no hay registros diarios coincidentes, data está vacío.
Ambos endpoints leen datos ya recopilados sin activar una actualización en la red social. El historial y las métricas disponibles dependen de la red, de los permisos y de los datos recopilados. Eliminar una cuenta también elimina sus analíticas; estos endpoints no archivan las cuentas eliminadas.
Obtén un resumen agregado del rendimiento de las cuentas
Resume las analíticas de cuentas con las mismas fechas y filtros opcionales de cuentas y redes:
GET /v1/workspaces/{workspace_id}/analytics/account-performance/summary?date_from=2026-08-01&date_to=2026-09-01&granularity=month&group_by=social_account
Parámetros opcionales adicionales:
granularity:day,monthoyear. Omítelo para todo el período solicitado.group_by:networkosocial_account. Omítelo para combinar las cuentas seleccionadas.
Estos parámetros son independientes. Combínalos para obtener una serie temporal por cuenta o red, u omite ambos para obtener un total de las cuentas y el período seleccionados.
{
"data": [
{
"analytics_period": {
"start": "2026-08-01",
"end": "2026-09-01",
"key": "2026-08"
},
"social_account_id": 123,
"analytics_refreshed_at": "2026-09-01T12:34:56Z",
"metrics": [
{ "name": "followers", "value": 1580, "aggregation": "last" },
{ "name": "views", "value": 42000, "aggregation": "sum" }
]
}
]
}
Con granularity, las filas incluyen analytics_period. Sus campos start y end, este último exclusivo, son los límites del intervalo de calendario; key utiliza YYYY-MM-DD, YYYY-MM o YYYY. Solo contribuyen los datos de las fechas solicitadas, por lo que un mes o año parcial no constituye un total del período completo. Sin granularidad, el campo de período se omite. Los resúmenes de cuentas no tienen campo timezone.
Con group_by, cada fila incluye network o social_account_id; sin él, no se devuelve ningún campo de agrupación. El resumen no está paginado.
Cada métrica incluye aggregation:
sum: suma los valores diarios del período solicitado.last: toma el último valor conocido de cada cuenta antes del final exclusivo del período y suma los valores entre cuentas. Se puede mantener un valor anterior al inicio solicitado. Por ejemplo, el número de seguidores suma las audiencias de las cuentas, no personas distintas entre cuentas.
Los resúmenes excluyen las medias, las tasas (incluida la tasa de interacción de LinkedIn del último año móvil) y la valoración global por estrellas (overall_star_rating). También se excluyen las métricas únicas clasificadas como medias. Estas métricas permanecen en los resultados diarios.
Los ceros conocidos se conservan; las métricas no disponibles o excluidas se omiten. analytics_refreshed_at es la fecha y hora de actualización UTC más reciente entre las filas de origen utilizadas, incluidos los valores mantenidos de fechas anteriores. No significa que todas las cuentas seleccionadas se hayan actualizado en ese momento.
Errores habituales
Clave de API no válida
{
"error": {
"code": "invalid_api_key",
"message": "The API key is invalid or has been revoked.",
"param": null,
"details": null,
"request_id": "req_abc123"
}
}
Plan obligatorio
{
"error": {
"code": "public_api_plan_required",
"message": "Public API access is available on Pro and Agency plans.",
"param": null,
"details": null,
"request_id": "req_abc123"
}
}
Error de validación
{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid.",
"param": "content_type",
"details": {
"reason": "The selected social account does not support this content type."
},
"request_id": "req_abc123"
}
}
Espacio de trabajo no encontrado
{
"error": {
"code": "workspace_not_found",
"message": "The requested workspace was not found.",
"param": "workspace_id",
"details": null,
"request_id": "req_abc123"
}
}
Buenas prácticas
- Guarda la clave de API de forma segura.
- No expongas la clave en código frontend.
- Comprueba en bytes los límites de tamaño de carga, importación y publicación antes de subir recursos multimedia.
- Sube o importa primero los recursos y espera hasta que su estado sea
ready. - Utiliza
GET /posts/{post_id}para comprobar el estado después de crear una publicación. - Trata los nombres de métricas como extensibles en lugar de codificar un conjunto fijo.
- Utiliza UTC en los filtros del resumen de publicaciones; al usar
granularity, interpreta las claves de intervalo según la zona horaria devuelta del espacio. Las analíticas de cuentas utilizan fechas de calendario almacenadas sin conversión de zona horaria. - Gestiona los errores de validación y muestra a tus usuarios el mensaje recibido.
- Reintenta únicamente después de respetar los encabezados de límite de solicitudes.
- Revoca la clave inmediatamente si crees que se ha expuesto.