> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sensorup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Emissions & LDAR API Guide

> Learn how to work with emission observations, LDAR workflows, reconciliation, and detection ingestion.

# Emissions & LDAR API Guide

The Emissions API provides comprehensive Leak Detection and Repair (LDAR) capabilities through three specialized subgraphs: `su-methane-ldar-backend`, `su-methane-reconcile-backend`, and `su-detections-ingress`.

## Overview

The Emissions API enables you to:

* Track and manage emission observations (detections)
* Coordinate LDAR inspection workflows
* Reconcile emissions for compliance reporting
* Ingest detection data from various sources

### Key Concepts

* **Emission Observation**: A detected emission event requiring investigation
* **Detection**: Raw detection data from sensors, flyovers, satellites, etc.
* **Inspection Request**: Request for follow-up inspection (OGI, drone, visual)
* **Reconciliation**: Process of matching emissions to compliance requirements
* **Clue**: Additional context about a detection (equipment, location, etc.)

## Emission Observations

### Query Emission Observations

```graphql theme={null}
query GetEmissionObservations($first: Int!, $after: String) {
  emissionObservations {
    all(first: $first, after: $after) {
      edges {
        node {
          id
          displayName
          priority
          status
          detectionType
          phenomenonTime
          receivedAt
          geometry {
            type
            coordinates
          }
          audit {
            createdTime
            acknowledgedTime
            acknowledgedBy {
              userId
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

### Get Specific Emission Observation

```graphql theme={null}
query GetEmissionObservation($id: ID!) {
  emissionObservations {
    byId(id: $id) {
      id
      displayName
      priority
      status
      detectionType
      phenomenonTime
      geometry {
        type
        coordinates
      }
      clues {
        clueId
        clue {
          displayName
          equipment {
            id
            name
          }
        }
      }
      inspectionRequests {
        inspectionRequestId
        inspectionRequest {
          id
          inspectionType
          status
          additionalComment
        }
      }
    }
  }
}
```

## Detection Types

| Type                                      | Description                  | Common Source     |
| ----------------------------------------- | ---------------------------- | ----------------- |
| `DETECTION_TYPE_SATELLITE`                | Satellite-based detection    | Remote sensing    |
| `DETECTION_TYPE_FLYOVER`                  | Aircraft-based detection     | Aerial surveys    |
| `DETECTION_TYPE_DRONE`                    | Drone-based detection        | UAV inspection    |
| `DETECTION_TYPE_OGI`                      | Optical Gas Imaging          | Ground inspection |
| `DETECTION_TYPE_CMS`                      | Continuous Monitoring System | Fixed sensors     |
| `DETECTION_TYPE_OWD`                      | On-site Walk Down            | Manual inspection |
| `DETECTION_TYPE_VENTING_FLARING_BLOWDOWN` | Planned releases             | Operations        |

## Detection Status Workflow

```mermaid theme={null}
stateDiagram-v2
    [*] --> NEW
    NEW --> VISUAL_INSPECTION_SCHEDULED
    VISUAL_INSPECTION_SCHEDULED --> VISUAL_INSPECTION_COMPLETED
    VISUAL_INSPECTION_COMPLETED --> OGI_REQUESTED
    OGI_REQUESTED --> OGI_SCHEDULED
    OGI_SCHEDULED --> OGI_COMPLETED
    OGI_COMPLETED --> LEAK_REPAIR_SCHEDULED
    LEAK_REPAIR_SCHEDULED --> LEAK_REPAIRED
    LEAK_REPAIRED --> VERIFICATION_SCHEDULED
    VERIFICATION_SCHEDULED --> RESOLVED
    RESOLVED --> [*]

    NEW: New Detection
    VISUAL_INSPECTION_SCHEDULED: Visual Inspection Scheduled
    VISUAL_INSPECTION_COMPLETED: Visual Inspection Completed
    OGI_REQUESTED: OGI Requested
    OGI_SCHEDULED: OGI Scheduled
    OGI_COMPLETED: OGI Completed
    LEAK_REPAIR_SCHEDULED: Leak Repair Scheduled
    LEAK_REPAIRED: Leak Repaired
    VERIFICATION_SCHEDULED: Verification Scheduled
    RESOLVED: Resolved
```

## Priority Levels

| Priority                    | Integer Value | Description                   |
| --------------------------- | ------------- | ----------------------------- |
| `DETECTION_PRIORITY_HIGH`   | 100           | Requires immediate attention  |
| `DETECTION_PRIORITY_MEDIUM` | 50            | Normal priority               |
| `DETECTION_PRIORITY_LOW`    | 1             | Low priority or informational |

## Inspection Requests

Inspection requests coordinate follow-up investigations of emission observations.

### Create Inspection Request

```graphql theme={null}
mutation CreateInspectionRequest($input: CreateInspectionRequestInput!) {
  createInspectionRequest(input: $input) {
    inspectionRequest {
      id
      detectionReference {
        detectionId
      }
      inspectionType
      status
      additionalComment
      audit {
        createdTime
        createdBy {
          userId
        }
      }
    }
    correlationId
    errors {
      message
      type
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "input": {
    "detectionReference": {
      "detectionId": "detection-123"
    },
    "inspectionType": "INSPECTION_OGI",
    "additionalComment": "High priority - investigate equipment leak",
    "clues": [
      {
        "clueId": "clue-456"
      }
    ],
    "requestedBy": {
      "givenName": "John",
      "familyName": "Doe",
      "email": "john.doe@example.com"
    }
  }
}
```

### Update Inspection Request

```graphql theme={null}
mutation UpdateInspectionRequest($input: UpdateInspectionRequestInput!) {
  updateInspectionRequest(input: $input) {
    inspectionRequest {
      id
      status
      additionalComment
    }
    correlationId
    errors {
      message
      type
    }
  }
}
```

### Query Inspection Requests

```graphql theme={null}
query GetInspectionRequests($detectionId: ID!) {
  emissionObservations {
    byId(id: $detectionId) {
      inspectionRequests {
        inspectionRequestId
        inspectionRequest {
          id
          inspectionType
          status
          additionalComment
          requestedBy {
            givenName
            familyName
            email
          }
          audit {
            createdTime
            updatedTime
          }
        }
      }
    }
  }
}
```

## Inspection Types

| Type               | Description         | Typical Use              |
| ------------------ | ------------------- | ------------------------ |
| `INSPECTION_OGI`   | Optical Gas Imaging | Confirm and locate leaks |
| `INSPECTION_DRONE` | Drone inspection    | Aerial investigation     |

## Clues (Equipment Context)

Clues provide context about where an emission was detected.

### Query Clues for Detection

```graphql theme={null}
query GetDetectionClues($detectionId: ID!) {
  emissionObservations {
    byId(id: $detectionId) {
      clues {
        clueId
        clue {
          displayName
          equipment {
            id
            name
            description
            siteReference {
              siteId
            }
            components {
              name
              componentType
            }
          }
        }
      }
    }
  }
}
```

### Equipment Components

```graphql theme={null}
query GetEquipmentComponents($equipmentId: ID!) {
  equipment {
    byId(id: $equipmentId) {
      id
      name
      components {
        name
        componentType
        description
      }
    }
  }
}
```

## Resolution Modes

When resolving emission observations:

| Mode                                    | Description                         |
| --------------------------------------- | ----------------------------------- |
| `DETECTION_RESOLVED_CORRELATED`         | Correlated with another detection   |
| `DETECTION_RESOLVED_FALSE_ALARM`        | Determined to be false positive     |
| `DETECTION_RESOLVED_READY_TO_RECONCILE` | Ready for compliance reconciliation |

### Resolve Detection

```graphql theme={null}
mutation ResolveDetection($input: ResolveDetectionInput!) {
  resolveDetection(input: $input) {
    emissionObservation {
      id
      status
      resolutionMode
    }
    correlationId
    errors {
      message
      type
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "input": {
    "detectionId": "detection-123",
    "resolutionMode": "DETECTION_RESOLVED_READY_TO_RECONCILE",
    "notes": "Verified and repaired, ready for compliance reporting"
  }
}
```

## Emission Observation Reports

### Query Reports by Site and Month

```graphql theme={null}
query GetEmissionReports($siteId: ID!, $month: String!) {
  sites {
    byId(id: $siteId) {
      emissionObservationReports(month: $month) {
        edges {
          node {
            month
            totalDetections
            resolvedDetections
            pendingDetections
            highPriorityCount
            complianceStatus
          }
        }
      }
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "siteId": "site-123",
  "month": "2025-11"
}
```

### Filter Reports

```graphql theme={null}
query FilteredReports($filter: InboxDetectionFilter!) {
  emissionObservations {
    reports(filter: $filter) {
      edges {
        node {
          id
          displayName
          priority
          status
        }
      }
    }
  }
}
```

## Detection Ingress

The `su-detections-ingress` subgraph handles incoming detection data.

### Query Available Datasets

```graphql theme={null}
query GetDetectionDatasets($group: ID) {
  detectionsIngressDatasets(group: $group) {
    datasetId
    metadataJson
  }
}
```

### Reload Datasets

```graphql theme={null}
mutation ReloadDatasets($group: ID) {
  reloadDetectionsIngressDatasets(group: $group) {
    datasetId
    metadataJson
  }
}
```

## Reconciliation Workflow

The `su-methane-reconcile-backend` handles compliance reconciliation.

### Query Reconciliation Status

```graphql theme={null}
query GetReconciliationStatus($siteId: ID!, $month: String!) {
  reconciliation {
    bySiteAndMonth(siteId: $siteId, month: $month) {
      status
      totalEmissions
      reconciledEmissions
      pendingEmissions
      complianceSeverity
      lastUpdated
    }
  }
}
```

### Submit for Reconciliation

```graphql theme={null}
mutation SubmitForReconciliation($input: SubmitReconciliationInput!) {
  submitForReconciliation(input: $input) {
    reconciliation {
      id
      status
      submittedAt
    }
    correlationId
    errors {
      message
      type
    }
  }
}
```

## Compliance Severity

| Severity | Description                 |
| -------- | --------------------------- |
| `HIGH`   | Critical compliance issue   |
| `MEDIUM` | Moderate compliance concern |
| `LOW`    | Minor compliance matter     |

## Geospatial Queries

### Get Detections Near Location

```graphql theme={null}
query GetNearbyDetections($center: GeoJSONGeometryInput!, $radius: Float!) {
  emissionObservations {
    near(center: $center, radius: $radius) {
      edges {
        node {
          id
          displayName
          geometry {
            type
            coordinates
          }
          distance
        }
      }
    }
  }
}
```

**Variables:**

```json theme={null}
{
  "center": {
    "type": "Point",
    "coordinates": [-114.0719, 51.0447]
  },
  "radius": 1000
}
```

## Audit & Acknowledgment

### Acknowledge Detection

```graphql theme={null}
mutation AcknowledgeDetection($input: AcknowledgeDetectionInput!) {
  acknowledgeDetection(input: $input) {
    emissionObservation {
      id
      audit {
        acknowledgedTime
        acknowledgedBy {
          userId
        }
      }
    }
    correlationId
    errors {
      message
      type
    }
  }
}
```

### Query Acknowledgment History

```graphql theme={null}
query GetAcknowledgmentHistory($detectionId: ID!) {
  emissionObservations {
    byId(id: $detectionId) {
      audit {
        createdTime
        createdBy {
          userId
        }
        updatedTime
        updatedBy {
          userId
        }
        acknowledgedTime
        acknowledgedBy {
          userId
        }
      }
    }
  }
}
```

## Common Patterns

### Processing New Detections

```javascript theme={null}
// Query new detections
const newDetections = await query(`
  query {
    emissionObservations {
      all(first: 100, filter: { status: DETECTION_STATUS_NEW }) {
        edges {
          node {
            id
            priority
            detectionType
            phenomenonTime
          }
        }
      }
    }
  }
`)

// Prioritize and create inspection requests
for (const detection of newDetections.filter(d => d.priority === 'HIGH')) {
  await createInspectionRequest({
    detectionId: detection.id,
    inspectionType: 'INSPECTION_OGI'
  })
}
```

### Tracking Inspection Progress

```javascript theme={null}
const inspectionStatuses = [
  'INSPECTION_STATUS_REQUESTED',
  'INSPECTION_STATUS_SCHEDULED',
  'INSPECTION_STATUS_COMPLETED'
]

for (const status of inspectionStatuses) {
  const count = await countInspections({ status })
  console.log(`${status}: ${count} inspections`)
}
```

## Best Practices

1. **Prioritize high-severity detections**: Focus on `DETECTION_PRIORITY_HIGH` first

2. **Track acknowledgment**: Always acknowledge when reviewing detections

3. **Use clues for context**: Clues help identify specific equipment and components

4. **Monitor status transitions**: Track detections through the complete workflow

5. **Coordinate inspections**: Link inspection requests to specific detections

6. **Reconcile regularly**: Don't let pending emissions accumulate

7. **Use geospatial queries**: Find nearby detections to optimize field work

8. **Archive resolved detections**: Keep historical data for compliance

## Related Resources

* **[LDAR Backend Reference](../subgraphs/methane-ldar-backend)** - Complete schema
* **[Reconcile Backend Reference](../subgraphs/methane-reconcile-backend)** - Reconciliation schema

## Schema Reference

* [su-methane-ldar-backend SDL](../schemas/sdl/su-methane-ldar-backend.graphql)
* [su-methane-reconcile-backend SDL](../schemas/sdl/su-methane-reconcile-backend.graphql)
* [su-detections-ingress SDL](../schemas/sdl/su-detections-ingress.graphql)