# Observability / Errors

## List and search error logs for an environment

> Returns paginated error log entries for a specific environment in a repository. Resolves the environment to its Salesforce org for querying. Supports predefined time ranges (last\_1h through last\_30d) or custom start/end dates. Full-text search across all error fields via the search parameter.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ErrorsListResponseDto":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ErrorsDashboardMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorLogRecord"}},"pagination":{"$ref":"#/components/schemas/PaginationMeta"},"summary":{"$ref":"#/components/schemas/ErrorsSummaryBlock"}},"required":["meta","errors","pagination","summary"]},"ErrorsDashboardMeta":{"type":"object","properties":{"repositoryIdentifier":{"type":"string"},"environmentName":{"type":"string"},"range":{"type":"string","description":"Predefined range name or \"custom\""},"start":{"type":"string"},"end":{"type":"string"},"generatedAt":{"type":"string"},"queryDurationMs":{"type":"number"}},"required":["repositoryIdentifier","range","start","end","generatedAt","queryDurationMs"]},"ErrorLogRecord":{"type":"object","properties":{"_time":{"type":"string"},"_msg":{"type":"string"},"error_type":{"type":"string","enum":["flow_failure","apex_exception"]},"org_id":{"type":"string"},"parse_status":{"type":"string","enum":["complete","partial","failed"]},"ingestion_path":{"type":"string","enum":["self_hosted","cloud","api"]},"flow_name":{"type":"string"},"failed_element":{"type":"string"},"error_detail":{"type":"string"},"impacted_user":{"type":"string"},"exception_type":{"type":"string"},"apex_class":{"type":"string"},"apex_method":{"type":"string"},"stack_trace":{"type":"string"},"exception_message":{"type":"string"},"raw_subject":{"type":"string"},"log_group":{"type":"string","enum":["error_logs","deployment_logs","audit_logs"]}},"required":["_time","_msg","error_type","org_id"]},"PaginationMeta":{"type":"object","properties":{"total":{"type":"number","description":"Total matching errors in time range"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]},"ErrorsSummaryBlock":{"type":"object","properties":{"total":{"type":"number"},"byType":{"type":"object"}},"required":["total","byType"]}}},"paths":{"/sfp/api/observability/errors":{"get":{"operationId":"ObservabilityErrorsController_listErrors","summary":"List and search error logs for an environment","description":"Returns paginated error log entries for a specific environment in a repository. Resolves the environment to its Salesforce org for querying. Supports predefined time ranges (last_1h through last_30d) or custom start/end dates. Full-text search across all error fields via the search parameter.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier","schema":{"type":"string"}},{"name":"environmentName","required":true,"in":"query","description":"Environment name","schema":{"type":"string"}},{"name":"range","required":false,"in":"query","description":"Predefined time range. Ignored if start/end are provided.","schema":{"enum":["last_1h","last_6h","last_24h","last_7d","last_30d"],"type":"string"}},{"name":"start","required":false,"in":"query","description":"Custom range start (ISO 8601). Requires end.","schema":{"type":"string"}},{"name":"end","required":false,"in":"query","description":"Custom range end (ISO 8601). Requires start.","schema":{"type":"string"}},{"name":"errorType","required":false,"in":"query","description":"Filter by error type","schema":{"enum":["flow_failure","apex_exception"],"type":"string"}},{"name":"search","required":false,"in":"query","description":"Full-text search across all error fields","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of results (1-500)","schema":{"default":50,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Pagination offset","schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":"Error logs retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorsListResponseDto"}}}},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Observability / Errors"]}}}}
```

## Get repo-wide error summary across all environments

> Returns aggregated error counts across all environments in a repository. Includes per-environment breakdown and time-series data. Useful for rendering overview dashboards. Supports predefined and custom date ranges.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ErrorsSummaryResponseDto":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ErrorsDashboardMeta"},"environments":{"type":"array","items":{"$ref":"#/components/schemas/EnvironmentErrorSummary"}},"total":{"type":"number"},"byType":{"type":"object"},"timeSeries":{"type":"array","items":{"$ref":"#/components/schemas/ErrorTimeSeries"}},"totalEnvironments":{"type":"number","description":"Total number of monitored environments in the repository"}},"required":["meta","environments","total","byType","timeSeries","totalEnvironments"]},"ErrorsDashboardMeta":{"type":"object","properties":{"repositoryIdentifier":{"type":"string"},"environmentName":{"type":"string"},"range":{"type":"string","description":"Predefined range name or \"custom\""},"start":{"type":"string"},"end":{"type":"string"},"generatedAt":{"type":"string"},"queryDurationMs":{"type":"number"}},"required":["repositoryIdentifier","range","start","end","generatedAt","queryDurationMs"]},"EnvironmentErrorSummary":{"type":"object","properties":{"environmentName":{"type":"string"},"orgId":{"type":"string"},"total":{"type":"number"},"byType":{"type":"object"}},"required":["environmentName","orgId","total","byType"]},"ErrorTimeSeries":{"type":"object","properties":{"label":{"type":"string","description":"Error type label"},"dataPoints":{"type":"array","items":{"$ref":"#/components/schemas/ErrorTimeSeriesPoint"}}},"required":["label","dataPoints"]},"ErrorTimeSeriesPoint":{"type":"object","properties":{"timestamp":{"type":"string"},"count":{"type":"number"}},"required":["timestamp","count"]}}},"paths":{"/sfp/api/observability/errors/summary":{"get":{"operationId":"ObservabilityErrorsController_getSummary","summary":"Get repo-wide error summary across all environments","description":"Returns aggregated error counts across all environments in a repository. Includes per-environment breakdown and time-series data. Useful for rendering overview dashboards. Supports predefined and custom date ranges.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier","schema":{"type":"string"}},{"name":"range","required":false,"in":"query","description":"Predefined time range. Ignored if start/end are provided.","schema":{"enum":["last_1h","last_6h","last_24h","last_7d","last_30d"],"type":"string"}},{"name":"start","required":false,"in":"query","description":"Custom range start (ISO 8601). Requires end.","schema":{"type":"string"}},{"name":"end","required":false,"in":"query","description":"Custom range end (ISO 8601). Requires start.","schema":{"type":"string"}}],"responses":{"200":{"description":"Summary retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorsSummaryResponseDto"}}}},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Observability / Errors"]}}}}
```

## Advanced raw LogsQL query

> Execute a raw LogsQL query against VictoriaLogs. For power users and debugging.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ErrorLogsQueryResponseDto":{"type":"object","properties":{"results":{"description":"Array of log entries matching the query","type":"array","items":{"type":"string"}}},"required":["results"]}}},"paths":{"/sfp/api/observability/errors/query":{"get":{"operationId":"ObservabilityErrorsController_queryRaw","summary":"Advanced raw LogsQL query","description":"Execute a raw LogsQL query against VictoriaLogs. For power users and debugging.","parameters":[{"name":"query","required":true,"in":"query","description":"LogsQL query string","schema":{"type":"string"}},{"name":"start","required":false,"in":"query","description":"Start time (ISO 8601 or relative like \"1h\")","schema":{"type":"string"}},{"name":"end","required":false,"in":"query","description":"End time (ISO 8601 or relative)","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of results to return","schema":{"type":"number"}}],"responses":{"200":{"description":"Query results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorLogsQueryResponseDto"}}}},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Observability / Errors"]}}}}
```

## Ingest pre-parsed error log entries

> Ingest structured error log entries into VictoriaLogs. Used by programmatic integrations.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ErrorLogsIngestDto":{"type":"object","properties":{"entries":{"description":"Array of error log entries to ingest","type":"array","items":{"$ref":"#/components/schemas/ErrorLogEntryDto"}}},"required":["entries"]},"ErrorLogEntryDto":{"type":"object","properties":{"_time":{"type":"string","description":"ISO 8601 timestamp"},"_msg":{"type":"string","description":"Human-readable error message"},"error_type":{"type":"string","enum":["flow_failure","apex_exception"],"description":"Type of Salesforce error"},"org_id":{"type":"string","description":"Salesforce org ID"},"parse_status":{"type":"string","enum":["complete","partial","failed"],"description":"Parse completeness status"},"ingestion_path":{"type":"string","enum":["self_hosted","cloud","api"],"description":"How the error was ingested"},"flow_name":{"type":"string","description":"Flow name (for flow_failure type)"},"failed_element":{"type":"string","description":"Failed element (for flow_failure type)"},"error_detail":{"type":"string","description":"Error detail message"},"exception_type":{"type":"string","description":"Exception type (for apex_exception type)"},"apex_class":{"type":"string","description":"Apex class name"},"apex_method":{"type":"string","description":"Apex method name"},"stack_trace":{"type":"string","description":"Stack trace"},"exception_message":{"type":"string","description":"Exception message"},"raw_subject":{"type":"string","description":"Original email subject"}},"required":["_time","_msg","error_type","org_id"]},"ErrorLogsIngestResponseDto":{"type":"object","properties":{"written":{"type":"number","description":"Number of log entries written"},"parseStatus":{"type":"string","description":"Parse status for email ingestion"},"message":{"type":"string","description":"Additional context message"}},"required":["written"]}}},"paths":{"/sfp/api/observability/errors/ingest":{"post":{"operationId":"ObservabilityErrorsController_ingest","summary":"Ingest pre-parsed error log entries","description":"Ingest structured error log entries into VictoriaLogs. Used by programmatic integrations.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorLogsIngestDto"}}}},"responses":{"201":{"description":"Log entries ingested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorLogsIngestResponseDto"}}}},"400":{"description":"Invalid request body"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Observability / Errors"]}}}}
```

## Ingest raw Salesforce error email

> Parse a raw Salesforce error email (Flow failure or Apex exception) and ingest into VictoriaLogs.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"RawEmailIngestDto":{"type":"object","properties":{"subject":{"type":"string","description":"Email subject line"},"body":{"type":"string","description":"Email body content"},"orgId":{"type":"string","description":"Optional org ID override"}},"required":["subject","body"]},"ErrorLogsIngestResponseDto":{"type":"object","properties":{"written":{"type":"number","description":"Number of log entries written"},"parseStatus":{"type":"string","description":"Parse status for email ingestion"},"message":{"type":"string","description":"Additional context message"}},"required":["written"]}}},"paths":{"/sfp/api/observability/errors/ingest/email":{"post":{"operationId":"ObservabilityErrorsController_ingestEmail","summary":"Ingest raw Salesforce error email","description":"Parse a raw Salesforce error email (Flow failure or Apex exception) and ingest into VictoriaLogs.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RawEmailIngestDto"}}}},"responses":{"201":{"description":"Email parsed and ingested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorLogsIngestResponseDto"}}}},"400":{"description":"Invalid request body"},"403":{"description":"Forbidden - Requires role: member, application"}},"tags":["Observability / Errors"]}}}}
```