Report Method

The method returns data for a funnel element.

Declare the Operation

Declare the method in application action OpenAPI using x-senler-app-action: version: 1, context: "funnel", read_only: true, result: { kind: "funnel_report" }. Enter its full name in the element, for example metrika__report. A method from another application or a method that changes data cannot be used.

Define the report extension directly in OpenAPI. The decorators and CLI in @senlerio/api version 0.4.0 do not support funnel; the method also does not appear as a separate plugin action in the MCP catalog. This does not prevent a connected funnel from receiving its report. See the section on the funnel context.

Request Parameters

Declare source_id, definition_id, definition_revision, metric_key, configuration, mode, date_from, date_to, timezone, cursor, limit, and include_records in the request body schema. Current mode sends null dates; periods include date_from and exclude date_to. A page contains at most 500 records, a period spans at most 366 days, and the response is limited to 2 MiB. General statistics are cached for one minute.

Response and Detail Records

The response contains mode, as_of, total, series, records, next_cursor, and records_complete. total: 0 is a measured zero; total: null means unavailable data. as_of is the data freshness timestamp. series contains non-overlapping { date_from, date_to, value } intervals and is available only in series mode.

A detail record contains a stable id, value, and either external_id or lead_id. The unused identifier is null. An exact event has occurred_at and two null period fields. A weekly per-person total has date_from, date_to, and occurred_at: null. Do not invent daily event dates from a weekly total. Repeated responses for a record preserve its id, identity, and original date or interval. Send corrected values with a newer as_of.

In current mode, all three record time fields may be null: this is current state without a known event date. These records match current lead variables without restoring historical attributions. A page containing undated records cannot be imported; as_of is not substituted for an event date. In period and series modes, an event date or interval is required.

Matching Leads

With identity: "none", records is empty and next_cursor is null. With external_id, the funnel selects a lead variable, its application scope, and a counter or account ID. The variable contains a scope:external_id string or an array of these strings. Matching stays within the project and selected variable scope. Multiple matching leads do not receive an attribution.

Reading a report does not save new matches. Import saves only unambiguous matches on the current page with their original dates or intervals. Reimport updates the same facts; editing a lead variable does not rewrite a saved attribution. A missing ID can be matched by reimporting after filling the variable, while the provider still offers that history. Aggregate numbers do not create leads or move them between stages.