> ## Documentation Index > Fetch the complete documentation index at: https://docs.pictor.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Os eventos de IA da janela > Os eventos que a análise de vídeo gerou na janela — o que foi visto, quando, em qual câmera, com que confiança, e a foto. `snapshot_url` e `snapshot_annotated_url` são endereços assinados e temporários (o segundo traz a marcação sobre a imagem). Como toda URL assinada aqui: guarde os bytes, não o link. **Filtre no servidor, não depois.** `min_score` e `review_status` entram na consulta antes do limite de linhas. Filtrar confiança do seu lado, sobre a página que chegou, produz um número que parece total e não é: "12 eventos acima de 90%" viraria "12 entre os últimos 50", não 12 no período. **Como avançar sem reler.** A resposta vem do mais recente para o mais antigo, limitada a `limit`. Para acompanhar sem varrer, guarde o `ts_start` do último evento que você já tem e use-o como `since` na próxima chamada. Se uma janela devolveu exatamente `limit` linhas, ela transbordou: estreite com `until` e caminhe para trás até esvaziar, senão os eventos mais antigos da janela ficam para trás em silêncio. Sem `since`, a janela padrão é de 24 horas. ## OpenAPI ````yaml /api-reference/openapi.json get /api/analytics/events openapi: 3.1.0 info: description: > API de leitura do Pictor Cloud para integração de parceiro. ## Autenticação Toda chamada leva a chave no cabeçalho `Authorization`: ``` Authorization: Bearer pct_1a2b3c4d_ ``` A chave é emitida por um **administrador da conta** no console (Integrações → Chaves de API) e **aparece uma única vez**, no momento da criação. O servidor guarda apenas o resumo criptográfico dela: não existe "mostrar de novo". Se perder, emita outra e revogue a antiga. ## O que a chave enxerga A chave carrega o mesmo par permissão/alcance de um usuário: | Campo | Valores | Efeito | |---|---|---| | `role` | `viewer`, `operator`, `admin` | `viewer` basta para tudo que está documentado aqui | | `scope` | `tenant`, `client`, `video_wall` | recorta o que a chave vê dentro da conta | Uma chave com `scope=client` só devolve as câmeras (e os eventos, e o diagnóstico) daquele cliente. Uma chave nunca atravessa a fronteira da conta que a emitiu: não existe chave que enxergue duas contas. ## Validade Toda chave tem prazo — "nunca expira" não é um estado que exista. Quando ela vence, as chamadas passam a responder `401`; a cura é emitir outra no console. ## Cabeçalhos que não se aplicam - `X-Tenant-ID`: opcional. Se vier, precisa ser a conta da própria chave; divergente responde `403`. A chave decide a conta, o cabeçalho nunca a troca. - `X-Membership-ID`: responde `403`. Uma chave não troca de workspace. ## Limites Há um teto de requisições por chave por minuto. Ao estourar, a resposta é `429` com `Retry-After`. A emissão de URL de mídia tem teto próprio, bem menor: cada sessão de vídeo custa CPU no servidor de mídia. ## Erros | Código | Significado | |---|---| | `401` | chave ausente, malformada, revogada ou expirada (o motivo não é detalhado, de propósito) | | `403` | chave válida, sem permissão para o recurso — ou cabeçalho que contradiz a chave | | `404` | o recurso não existe **ou** não é desta chave (não distinguimos: dizer qual seria contar o que existe) | | `429` | teto de requisições estourado | title: Pictor Cloud — API de parceiro version: 1.0.0 servers: - description: Pictor Cloud url: https://api.pictor.cloud security: [] paths: /api/analytics/events: get: tags: - Analytics summary: Os eventos de IA da janela description: >- Os eventos que a análise de vídeo gerou na janela — o que foi visto, quando, em qual câmera, com que confiança, e a foto. `snapshot_url` e `snapshot_annotated_url` são endereços assinados e temporários (o segundo traz a marcação sobre a imagem). Como toda URL assinada aqui: guarde os bytes, não o link. **Filtre no servidor, não depois.** `min_score` e `review_status` entram na consulta antes do limite de linhas. Filtrar confiança do seu lado, sobre a página que chegou, produz um número que parece total e não é: "12 eventos acima de 90%" viraria "12 entre os últimos 50", não 12 no período. **Como avançar sem reler.** A resposta vem do mais recente para o mais antigo, limitada a `limit`. Para acompanhar sem varrer, guarde o `ts_start` do último evento que você já tem e use-o como `since` na próxima chamada. Se uma janela devolveu exatamente `limit` linhas, ela transbordou: estreite com `until` e caminhe para trás até esvaziar, senão os eventos mais antigos da janela ficam para trás em silêncio. Sem `since`, a janela padrão é de 24 horas. operationId: list_events_api_analytics_events_get parameters: - in: query name: device_id required: false schema: anyOf: - format: uuid type: string - type: 'null' title: Device Id - in: query name: label required: false schema: anyOf: - type: string - type: 'null' title: Label - in: query name: since required: false schema: anyOf: - format: date-time type: string - type: 'null' title: Since - in: query name: until required: false schema: anyOf: - format: date-time type: string - type: 'null' title: Until - description: Confiança mínima (0..1). Filtra NO BANCO, antes do limite. in: query name: min_score required: false schema: anyOf: - maximum: 1 minimum: 0 type: number - type: 'null' description: Confiança mínima (0..1). Filtra NO BANCO, antes do limite. title: Min Score - description: Recorte pelo veredito do operador. in: query name: review_status required: false schema: anyOf: - pattern: ^(unreviewed|true_positive|false_positive|reviewed)$ type: string - type: 'null' description: Recorte pelo veredito do operador. title: Review Status - in: query name: limit required: false schema: default: 50 maximum: 500 minimum: 1 title: Limit type: integer - in: header name: X-Membership-ID required: false schema: anyOf: - type: string - type: 'null' title: X-Membership-Id - in: header name: X-Tenant-ID required: false schema: anyOf: - type: string - type: 'null' title: X-Tenant-Id responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/AnalyticsEventResponse' title: Response List Events Api Analytics Events Get type: array description: Successful Response '401': description: Chave ausente, invalida, revogada ou expirada. '403': description: Chave valida, sem permissao para o recurso. '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error '429': description: Teto de requisicoes desta chave excedido. security: - HTTPBearer: [] components: schemas: AnalyticsEventResponse: properties: alarm_id: anyOf: - format: uuid type: string - type: 'null' title: Alarm Id bbox: anyOf: - maxItems: 4 minItems: 4 prefixItems: - type: number - type: number - type: number - type: number type: array - type: 'null' title: Bbox camera_name: anyOf: - type: string - type: 'null' title: Camera Name clip_path: anyOf: - type: string - type: 'null' title: Clip Path device_id: format: uuid title: Device Id type: string event_id: format: uuid title: Event Id type: string label: title: Label type: string model_id: anyOf: - type: string - type: 'null' title: Model Id payload: additionalProperties: true title: Payload type: object profile_id: format: uuid title: Profile Id type: string review_reason: anyOf: - type: string - type: 'null' title: Review Reason review_status: default: unreviewed enum: - unreviewed - true_positive - false_positive title: Review Status type: string reviewed_at: anyOf: - format: date-time type: string - type: 'null' title: Reviewed At reviewed_by: anyOf: - format: uuid type: string - type: 'null' title: Reviewed By score: title: Score type: number snapshot_annotated_path: anyOf: - type: string - type: 'null' title: Snapshot Annotated Path snapshot_annotated_url: anyOf: - type: string - type: 'null' title: Snapshot Annotated Url snapshot_path: anyOf: - type: string - type: 'null' title: Snapshot Path snapshot_url: anyOf: - type: string - type: 'null' title: Snapshot Url tenant_id: format: uuid title: Tenant Id type: string track_id: anyOf: - type: string - type: 'null' title: Track Id ts_end: anyOf: - format: date-time type: string - type: 'null' title: Ts End ts_start: format: date-time title: Ts Start type: string type: title: Type type: string required: - event_id - tenant_id - device_id - profile_id - type - label - score - ts_start title: AnalyticsEventResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object securitySchemes: HTTPBearer: description: Chave de API da conta, no formato `pct__`. scheme: bearer type: http ````