# 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.9.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","description":"Omitted when the response aggregates across all repositories"},"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":["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.9.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"},"orgs":{"description":"One entry per Salesforce org (deduped across environments)","type":"array","items":{"$ref":"#/components/schemas/OrgErrorSummary"}},"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","orgs","total","byType","timeSeries","totalEnvironments"]},"ErrorsDashboardMeta":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Omitted when the response aggregates across all repositories"},"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":["range","start","end","generatedAt","queryDurationMs"]},"OrgErrorSummary":{"type":"object","properties":{"orgUsername":{"type":"string","description":"Salesforce username identifying the org"},"orgId":{"type":"string","description":"15-char Salesforce org id"},"environmentLabels":{"description":"Every (env name, repo) pair that points to this org","type":"array","items":{"$ref":"#/components/schemas/EnvironmentLabelDto"}},"total":{"type":"number"},"byType":{"type":"object"}},"required":["orgUsername","orgId","environmentLabels","total","byType"]},"EnvironmentLabelDto":{"type":"object","properties":{"name":{"type":"string","description":"Environment name within its repository"},"repositoryIdentifier":{"type":"string","description":"Repository the environment belongs to"}},"required":["name","repositoryIdentifier"]},"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":false,"in":"query","description":"Repository identifier. When omitted, the summary aggregates across every environment in the tenant.","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.9.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.9.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.9.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"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/observability-errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.