# Poll for Updates

> Pod Engine API endpoint reference, optimized for LLM consumption.
> Auto-generated from the source-of-truth endpoint registry.
>
> Category: Polling
> Source: https://www.podengine.ai/api-docs/polling-updates.md
> Interactive HTML docs: https://www.podengine.ai/api-docs/polling-updates
> Full API reference (all endpoints): https://www.podengine.ai/api-docs/llms.txt

**Base URL:** `http://localhost:4000`
**Auth:** Requires a Bearer token: `Authorization: Bearer YOUR_API_KEY`

---

#### GET /api/v1/polling/updates
**Poll for Updates**

Poll for updates across your team. Returns a chronological feed of events (completed requests, new guest appearances, podcasts added to projects, alert matches) since a given timestamp or cursor. Designed for regular polling — use the returned cursor for efficient subsequent calls.

```bash
curl -X GET "http://localhost:4000/api/v1/polling/updates?limit=10" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Query schema:**
```json
{
  "type": "object",
  "properties": {
    "since": {
      "description": "ISO 8601 timestamp. Return events after this point. Ignored if cursor is provided. Max lookback: 30 days.",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "cursor": {
      "description": "Opaque cursor from a previous response. Takes precedence over since.",
      "type": "string"
    },
    "eventTypes": {
      "description": "Comma-separated list of event types to include: request_completed, guest_appearance, listed_podcast_added, alert_match. Default: all.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "request_completed",
          "guest_appearance",
          "listed_podcast_added",
          "alert_match"
        ]
      }
    },
    "projectId": {
      "description": "Filter listed_podcast_added events to a specific project.",
      "type": "string"
    },
    "guestProfileId": {
      "description": "Filter guest_appearance events to a specific guest profile.",
      "type": "string"
    },
    "alertConfigId": {
      "description": "Filter alert_match events to a specific alert configuration.",
      "type": "string"
    },
    "limit": {
      "description": "Max events per page (1-100, default 50).",
      "type": "number",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "limit"
  ],
  "additionalProperties": false
}
```

**Response schema:**
```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "OK"
      ]
    },
    "options": {
      "type": "object",
      "properties": {
        "since": {
          "nullable": true,
          "description": "The resolved since timestamp used for this query.",
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        "cursor": {
          "nullable": true,
          "description": "The cursor provided in this request, if any.",
          "type": "string"
        },
        "eventTypes": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "request_completed",
              "guest_appearance",
              "listed_podcast_added",
              "alert_match"
            ]
          },
          "description": "The event types included in this query."
        },
        "limit": {
          "type": "number",
          "description": "The maximum number of events per page."
        },
        "projectId": {
          "nullable": true,
          "description": "Project filter applied, if any.",
          "type": "string"
        },
        "guestProfileId": {
          "nullable": true,
          "description": "Guest profile filter applied, if any.",
          "type": "string"
        },
        "alertConfigId": {
          "nullable": true,
          "description": "Alert config filter applied, if any.",
          "type": "string"
        }
      },
      "required": [
        "since",
        "cursor",
        "eventTypes",
        "limit",
        "projectId",
        "guestProfileId",
        "alertConfigId"
      ],
      "additionalProperties": false,
      "description": "The resolved options used for this query."
    },
    "data": {
      "type": "object",
      "properties": {
        "events": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event identifier."
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                    "description": "When this event occurred (ISO 8601)."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "request_completed"
                    ]
                  },
                  "data": {
                    "type": "object",
                    "properties": {
                      "requestId": {
                        "type": "string"
                      },
                      "requestType": {
                        "type": "string",
                        "enum": [
                          "autoOutreach",
                          "deepAnalysis",
                          "diarization",
                          "guestPrep",
                          "transcription"
                        ]
                      },
                      "podcastId": {
                        "type": "string"
                      },
                      "episodeId": {
                        "nullable": true,
                        "type": "string"
                      },
                      "guestProfileId": {
                        "nullable": true,
                        "type": "string"
                      },
                      "completedAt": {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                      },
                      "error": {
                        "nullable": true,
                        "type": "string"
                      }
                    },
                    "required": [
                      "requestId",
                      "requestType",
                      "podcastId",
                      "episodeId",
                      "guestProfileId",
                      "completedAt",
                      "error"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "id",
                  "occurredAt",
                  "eventType",
                  "data"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event identifier."
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                    "description": "When this event occurred (ISO 8601)."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "guest_appearance"
                    ]
                  },
                  "data": {
                    "type": "object",
                    "properties": {
                      "guestAppearanceId": {
                        "type": "string"
                      },
                      "guestProfileId": {
                        "type": "string"
                      },
                      "episodeId": {
                        "type": "string"
                      },
                      "aiVerified": {
                        "nullable": true,
                        "type": "boolean"
                      },
                      "humanVerified": {
                        "nullable": true,
                        "type": "boolean"
                      },
                      "createdAt": {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                      }
                    },
                    "required": [
                      "guestAppearanceId",
                      "guestProfileId",
                      "episodeId",
                      "aiVerified",
                      "humanVerified",
                      "createdAt"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "id",
                  "occurredAt",
                  "eventType",
                  "data"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event identifier."
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                    "description": "When this event occurred (ISO 8601)."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "listed_podcast_added"
                    ]
                  },
                  "data": {
                    "type": "object",
                    "properties": {
                      "listedPodcastId": {
                        "type": "string"
                      },
                      "projectId": {
                        "type": "string"
                      },
                      "podcastId": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "prospect",
                          "qualified",
                          "pitched",
                          "lost",
                          "booked",
                          "ignored"
                        ]
                      },
                      "createdAt": {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                      }
                    },
                    "required": [
                      "listedPodcastId",
                      "projectId",
                      "podcastId",
                      "status",
                      "createdAt"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "id",
                  "occurredAt",
                  "eventType",
                  "data"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Unique event identifier."
                  },
                  "occurredAt": {
                    "type": "string",
                    "format": "date-time",
                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
                    "description": "When this event occurred (ISO 8601)."
                  },
                  "eventType": {
                    "type": "string",
                    "enum": [
                      "alert_match"
                    ]
                  },
                  "data": {
                    "type": "object",
                    "properties": {
                      "alertMatchId": {
                        "type": "string"
                      },
                      "alertConfigId": {
                        "type": "string"
                      },
                      "alertConfigName": {
                        "type": "string"
                      },
                      "alertType": {
                        "type": "string",
                        "enum": [
                          "TRANSCRIPT",
                          "EPISODE"
                        ]
                      },
                      "episodeId": {
                        "type": "string"
                      },
                      "podcastId": {
                        "type": "string"
                      },
                      "createdAt": {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
                      }
                    },
                    "required": [
                      "alertMatchId",
                      "alertConfigId",
                      "alertConfigName",
                      "alertType",
                      "episodeId",
                      "podcastId",
                      "createdAt"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "id",
                  "occurredAt",
                  "eventType",
                  "data"
                ],
                "additionalProperties": false
              }
            ]
          }
        },
        "cursor": {
          "nullable": true,
          "description": "Pass this value as the cursor query parameter on your next poll. Null if no results.",
          "type": "string"
        },
        "hasMore": {
          "type": "boolean",
          "description": "True if there are more events beyond this page."
        }
      },
      "required": [
        "events",
        "cursor",
        "hasMore"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "status",
    "options",
    "data"
  ],
  "additionalProperties": false
}
```

---

## See also

- All endpoints in one file: https://www.podengine.ai/api-docs/llms.txt
- Full reference with every schema inlined: https://www.podengine.ai/api-docs/llms-full.txt
- OpenAPI 3.1 spec: https://www.podengine.ai/api-docs/openapi.json
- Get an API key: https://www.podengine.ai/get-started
- Support: support@podengine.ai