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 listar tus espacios de trabajo y cuentas sociales conectadas, subir recursos multimedia, crear y gestionar publicaciones y obtener analíticas actuales o agregadas.

Public API 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_id en 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

1. Abre Postoria.
2. Ve a Settings.
3. Busca la sección Public API.
4. Haz clic en Create API key.
5. 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 Public API incluye estos endpoints:

GET    /v1/workspaces

GET    /v1/workspaces/{workspace_id}/social-accounts
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

Lista los espacios de trabajo

Utiliza este endpoint para obtener los espacios disponibles en tu cuenta:

GET /v1/workspaces

Ejemplo de respuesta:

{
  "data": [
    {
      "id": 1,
      "name": "My Workspace",
      "timezone": "America/New_York"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Utiliza el id devuelto como workspace_id en los endpoints específicos del espacio.

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",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Utiliza los ID devueltos en social_account_ids al crear publicaciones.

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:

1. Crear una URL de carga y subir el archivo por tu cuenta.
2. 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.

Los tipos compatibles incluyen formatos habituales de imagen, vídeo y documentos, como JPEG, PNG, WebP, GIF, MP4, MOV y PDF.

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"
  }
}

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"
}

Ejemplo de respuesta:

{
  "id": 9002,
  "status": "processing",
  "file_id": null,
  "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.

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 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_upload
• processing
• ready
• failed

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_now
• schedule
• queue

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 archivo también puede incluir thumbnail_url si hay una miniatura disponible.

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 Stories 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:

• text
• image
• video
• document
• carousel
• link
• story
• reel

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, video o document
• 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.

{
  "media": [
    {
      "media_id": 9001
    }
  ]
}

En un vídeo puedes proporcionar opcionalmente una miniatura personalizada. thumbnail_media_id pertenece al media_id correspondiente y debe hacer referencia a una imagen lista.

{
  "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": {
    "also_publish_media_to_stories": true
  }
}

Cuando also_publish_media_to_stories es true, Postoria crea primero la publicación normal y después publica cada archivo adjunto como una Story 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": {
    "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
      }
    ]
  }
}

Cuando also_publish_media_to_stories es true, Postoria crea primero la publicación normal y después publica cada archivo adjunto como una Story 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 Bulk Upload: 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, friends o private
• allow_comments: true o false
• allow_duet: true o false
• allow_stitch: true o false
• disclose_post_content: true o false
• your_brand: true o false
• branded_content: true o false
• photo_title: texto sin formato de hasta 90 caracteres
• auto_add_music: true o false

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 de draft, scheduled, in_progress, posted o queued.
• networks: uno o varios valores de red, como instagram, facebook, linkedin, youtube o tiktok.
• 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 es 25 y el máximo es 100.
• 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:

• draft
• scheduled
• in_progress
• posted
• queued

Significado de los elementos de resultado:

• link_to_post contiene un valor cuando la publicación se ha publicado correctamente y hay un enlace público disponible.
• error contiene un valor cuando ha fallado la publicación para esa cuenta.
• Tanto link_to_post como error pueden ser null antes 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",
      "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. Un cero conocido se devuelve como cero. Si existe una publicación, pero todavía no hay analíticas, 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 youtube_. Algunos ejemplos son youtube_views, youtube_engaged_views, youtube_likes, youtube_dislikes, youtube_estimated_minutes_watched, youtube_average_view_duration y youtube_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 con Z o +00:00.
• published_to: marca de tiempo UTC ISO 8601 exclusiva con Z o +00:00.

El intervalo debe ser superior a cero y no puede superar 366 días.

Parámetros opcionales:

• granularity: hour, day, month o year. Omítelo para no devolver intervalos temporales de publicación.
• group_by: network, content_type o social_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.

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.
• 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; al usar granularity, interpreta las claves de intervalo según la zona horaria devuelta del espacio.
• 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.