Discover BI Datasets and Schemas¶

FieldOps provides discovery endpoints that allow you to inspect the BI data available to your organization before building reports, queries, or integrations.

You can use these endpoints to:

Discover available BI datasets
Inspect a specific dataset and its available dimensions
Inspect the schema of a BI table
Identify fields before building filters and queries

This is useful when configuring a new analytics workflow or exploring the BI data available through FieldOps.

Before you begin¶

You need:

A valid FieldOps BI Access Token
Access to your FieldOps organization's BI data
A tool that can make authenticated HTTPS requests

Every protected request should include your BI Access Token as a Bearer token:

Authorization: Bearer YOUR_BI_ACCESS_TOKEN

For example:

Authorization: Bearer fldops_bi_XXXXXXXX

Warning

Never include a real BI Access Token in public documentation, screenshots, source code repositories, or support messages.

Discover available datasets¶

Use the dataset discovery endpoint to retrieve the BI datasets available through FieldOps.

GET /api/bi/datasets

Production endpoint:

https://app.fieldopsafrica.com/api/bi/datasets

Example request:

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/datasets"

Use the response to identify the datasets currently available for analysis.

Tip

Start with the dataset discovery endpoint when you are unsure which BI datasets are available.

Inspect a specific dataset¶

After identifying an available dataset, you can inspect it in more detail.

The endpoint follows this structure:

GET /api/bi/datasets/{dataset}

Replace {dataset} with the dataset name.

For example:

GET /api/bi/datasets/visits

Production endpoint:

https://app.fieldopsafrica.com/api/bi/datasets/visits

Example request:

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/datasets/visits"

Use this endpoint to inspect information about the dataset, including the dimensions available for working with it.

Dataset dimensions¶

Dimensions are fields that can be used to describe, organize, group, or filter data.

Depending on the dataset, dimensions may represent operational concepts such as:

Programme
Project
Site
User
Status
Date
Other dataset-specific attributes

For example, a visits dataset may expose dimensions that help an analytics workflow examine visit activity by Programme, Project, Site, status, or reporting period.

Note

Available dimensions depend on the dataset. Use the dataset endpoint to inspect the dimensions currently available for the dataset you want to analyze.

Dataset names and BI table names¶

Dataset names and BI table names serve related but different purposes.

For example:

Dataset:
visits

may be inspected using:

GET /api/bi/datasets/visits

A BI table may be queried using:

GET /api/bi/tables/bi_visits

And its schema may be inspected using:

GET /api/bi/schema/bi_visits

The general pattern is:

Purpose	Endpoint
Discover datasets	`/api/bi/datasets`
Inspect a dataset	`/api/bi/datasets/{dataset}`
Retrieve BI data	`/api/bi/tables/{table}`
Inspect a table schema	`/api/bi/schema/{table}`

Tip

Use dataset discovery to understand the analytical datasets available, and schema discovery to inspect the structure of a specific BI table.

Available BI tables¶

FieldOps currently provides the following BI tables:

BI table	Purpose
`bi_visits`	Visit-level operational and monitoring data
`bi_visit_responses`	Responses captured during visits
`bi_daily_visit_metrics`	Daily aggregated visit metrics
`bi_program_performance_snapshots`	Programme-level performance snapshots
`bi_question_response_aggregates`	Aggregated monitoring question responses

Retrieve data from a BI table¶

The general BI table endpoint is:

GET /api/bi/tables/{table}

For example:

GET /api/bi/tables/bi_visits

Production endpoint:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits

Another example:

GET /api/bi/tables/bi_visit_responses

Production endpoint:

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses

For detailed filtering and query examples, see:

Query BI Data

Inspect a BI table schema¶

Before building queries against a BI table, you can inspect its schema.

The schema endpoint follows this structure:

GET /api/bi/schema/{table}

Replace {table} with the BI table name.

For example:

GET /api/bi/schema/bi_visits

Production endpoint:

https://app.fieldopsafrica.com/api/bi/schema/bi_visits

Example request:

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/schema/bi_visits"

Schema discovery can help you understand the fields available in a BI table before retrieving or filtering its data.

Schema endpoints for available BI tables¶

Visits¶

GET /api/bi/schema/bi_visits

Production endpoint:

https://app.fieldopsafrica.com/api/bi/schema/bi_visits

Visit responses¶

GET /api/bi/schema/bi_visit_responses

Production endpoint:

https://app.fieldopsafrica.com/api/bi/schema/bi_visit_responses

Daily visit metrics¶

GET /api/bi/schema/bi_daily_visit_metrics

Production endpoint:

https://app.fieldopsafrica.com/api/bi/schema/bi_daily_visit_metrics

Programme performance snapshots¶

GET /api/bi/schema/bi_program_performance_snapshots

Production endpoint:

https://app.fieldopsafrica.com/api/bi/schema/bi_program_performance_snapshots

Question response aggregates¶

GET /api/bi/schema/bi_question_response_aggregates

Production endpoint:

https://app.fieldopsafrica.com/api/bi/schema/bi_question_response_aggregates

Recommended discovery workflow¶

When building a new report, dashboard, or data integration, use the following workflow.

Step 1: Discover available datasets¶

Request:

GET /api/bi/datasets

Use the response to identify the analytical datasets available through FieldOps.

Step 2: Inspect the dataset¶

Request:

GET /api/bi/datasets/{dataset}

For example:

GET /api/bi/datasets/visits

Use the response to understand the dataset and its available dimensions.

Step 3: Inspect the BI table schema¶

Request:

GET /api/bi/schema/{table}

For example:

GET /api/bi/schema/bi_visits

Use the schema to understand the fields available in the BI table.

Step 4: Build a filtered query¶

Request data from:

GET /api/bi/tables/{table}

For example:

GET /api/bi/tables/bi_visits?status=eq:approved

Or:

GET /api/bi/tables/bi_visits?program_id=in:1,2&visit_date=between:2026-01-01,2026-06-30

Step 5: Inspect the response metadata¶

When data is returned, inspect:

meta
query_guard
pagination

These objects help you understand:

How the request was resolved
Whether the result is aggregated
Whether FieldOps applied query safeguards
Whether additional pages are available

Example discovery workflow¶

A new analytics integration could begin by requesting:

https://app.fieldopsafrica.com/api/bi/datasets

After discovering the visits dataset, inspect it:

https://app.fieldopsafrica.com/api/bi/datasets/visits

Then inspect the related BI table schema:

https://app.fieldopsafrica.com/api/bi/schema/bi_visits

Finally, retrieve the required data:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?status=eq:approved

This discovery-first approach makes it easier to understand the available BI data before building queries and reports.

Choosing between datasets, schemas, and tables¶

Use the following guide:

Use `/api/bi/datasets` when:¶

You want to discover available BI datasets
You are beginning a new analytics integration
You want to understand what analytical data is available

Use `/api/bi/datasets/{dataset}` when:¶

You want to inspect a specific dataset
You want to see its available dimensions
You are planning how to analyze the dataset

Use `/api/bi/schema/{table}` when:¶

You need to inspect the fields available in a BI table
You are preparing transformations
You are building filters
You are validating expected columns

Use `/api/bi/tables/{table}` when:¶

You are ready to retrieve BI data
You want to apply filters
You want to load data into an external analytics workflow

Safe query considerations¶

Discovering a dataset or inspecting a schema before retrieving data can help you build more focused BI queries.

Where possible:

Inspect the available dataset first
Inspect the BI table schema
Select the fields and dimensions relevant to your analysis
Apply filters when retrieving large datasets
Use date ranges where appropriate
Follow pagination when additional pages are available
Inspect query_guard for warnings or enforced limits

Important

FieldOps may apply query safeguards or serve broad analytical requests from optimized BI datasets. Always inspect the response metadata when integrating with the BI API.

What to do next¶

You now have the core information required to work with the FieldOps BI API:

Create a BI Access Token
Understand the BI API
Build filtered queries
Discover datasets and schemas

Query BI data

Review the BI API

Discover BI Datasets and Schemas¶

Before you begin¶

Discover available datasets¶

Inspect a specific dataset¶

Dataset dimensions¶

Dataset names and BI table names¶

Available BI tables¶

Retrieve data from a BI table¶

Inspect a BI table schema¶

Schema endpoints for available BI tables¶

Visits¶

Visit responses¶

Daily visit metrics¶

Programme performance snapshots¶

Question response aggregates¶

Recommended discovery workflow¶

Step 1: Discover available datasets¶

Step 2: Inspect the dataset¶

Step 3: Inspect the BI table schema¶

Step 4: Build a filtered query¶

Step 5: Inspect the response metadata¶

Example discovery workflow¶

Choosing between datasets, schemas, and tables¶

Use /api/bi/datasets when:¶

Use /api/bi/datasets/{dataset} when:¶

Use /api/bi/schema/{table} when:¶

Use /api/bi/tables/{table} when:¶

Safe query considerations¶

What to do next¶

Use `/api/bi/datasets` when:¶

Use `/api/bi/datasets/{dataset}` when:¶

Use `/api/bi/schema/{table}` when:¶

Use `/api/bi/tables/{table}` when:¶