Discover IDs
list_projects returns projects the caller can access. get_project returns project details and brand context. Use that context to check the brand terms and owned domains you intend to report.
list_runs returns runs newest first. Treat each run_id as an opaque string and pass it back unchanged. Current run-detail requests require a UUID. Do not convert the ID to a number or substitute a job ID.
Check the run state
Do not treat a null count as zero. Some run-detail counts are unavailable even when useful measurements exist. Use a metric tool for the actual measurement rather than reconstructing it from run counters.
Keep comparisons comparable
Use explicit run IDs for recurring reports. Record the selected topics, platforms, brand definitions, and filters. A changed project configuration can change the population being measured. A difference between two runs does not by itself establish that a content edit caused the difference.start_session finds the most recent run, including one still in progress. It is useful for a conversation, but a scheduled reporting application should select and check its own run.
Next: Choose filters and subjects.