1. Telemetry & Data Acquisition
FoxCloud OpenAPI
Vpp Flow
  • Vpp Flow
  • Full API Reference
  • What's New & Milestones
  • Getting Started
    • 1. Overview & Integration Scope
    • 2. Environments & Prerequisites
  • End-User Enrollment & OAuth Flow
    • 0. Introduction
    • 1. The User Authorization Journey
    • 2. OAuth Token Operating Model
    • 3. Implementation Guide
  • API Technical Specifications
    • 1. Universal Request Rules
    • 2. Rate Limiting Strategy
    • 3. Response Structure
    • 4. Error Code Reference
  • Telemetry & Data Acquisition
    • 1. Data Pipeline & Scaling Strategy
    • 2. Telemetry Data Query (Real-time)
    • 4. Telemetry Variable Dictionary
    • 5. System Performance & SLA
    • 3. Device Configuration & Settings: Pre-Dispatch State Awareness
  • Control Commands & Dispatch
    • 1. Core Dispatch Architecture: Scheduler V3
    • 2. Scheduler V3 Operations
    • 3. Real-time Device Settings
    • 4. Strategic Roadmap: Scaling for Massive Fleets
  • FAQ
    • Troubleshooting Quick Guide
  1. Telemetry & Data Acquisition

2. Telemetry Data Query (Real-time)

Once you have the deviceSn, you can fetch the current operational status of your assets. This section focuses on the Real-time Data Query mechanism, which is ideal for fetching the latest snapshots of device variables on demand.

3.1 Core API Endpoint#

API Endpoint: POST /op/v1/device/real/query
Business Logic: Fetches the most recent data points reported by the device for the specified variables (e.g., pvPower, batterySoc, gridConsumptionPower).

3.2 Key Request Parameters & Constraints#

To ensure system stability and fair resource allocation, the real-time query interface enforces the following constraints:
ParameterTypeDescriptionConstraints
snsArrayAn array of device serial numbers.Supports batch querying, but max 50 devices per request.
variablesArrayAn array of variable keys you wish to fetch.Refer to the Telemetry Variable Dictionary for supported keys.
Performance Tip: If you need to fetch data for more than 50 devices, you must split your sns array into multiple requests and execute them in parallel or sequentially.

3.3 Polling vs. Streaming: When to Use Real-time Query?#

While real/query is powerful, it is a Pull-based mechanism. Use the following guide to decide if it fits your scenario:
Use Real-time Query (real/query) when:
You need to fetch data on-demand (e.g., when a user opens a dashboard page).
Your VPP operates on a standard 5-minute polling interval for billing or daily reporting.
You are managing a small to medium-scale fleet.
Use Kafka Streaming when:
You require near real-time data (< 1 minute latency) for high-frequency grid balancing.
You are managing a massive fleet and want to avoid the overhead of thousands of HTTP polling requests.
Reference: For the complete JSON request body structure, exact parameter formatting, and response examples, please refer to the Full API Reference List and search for /op/v1/device/real/query.
Modified at 2026-07-21 08:27:08
Previous
1. Data Pipeline & Scaling Strategy
Next
4. Telemetry Variable Dictionary
Built with