Query BI Data¶

FieldOps BI table endpoints support filtering, advanced query operators, result limits, and pagination.

Use these capabilities to request only the data required by your reporting or analytics workflow.

The general BI table endpoint is:

GET /api/bi/tables/{table}

For example:

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

Every request must include a valid FieldOps BI Access Token.

Before you begin¶

You need:

A valid FieldOps BI Access Token
The BI table you want to query
The fields or dimensions you want to filter
A tool that can make authenticated HTTPS requests

If you are unsure which BI tables are available, use the dataset and schema discovery endpoints described in the FieldOps BI API overview.

Authentication¶

Send your BI Access Token as a Bearer token:

Authorization: Bearer YOUR_BI_ACCESS_TOKEN

For example:

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

Warning

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

Basic query structure¶

A query parameter is added after ? in the endpoint URL.

For example:

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

Additional query parameters are separated using &.

For example:

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

Direct filters¶

FieldOps BI endpoints can accept filters such as:

site_id
program_id
project_id
user_id
status
date_from
date_to
limit

The filters that are meaningful for a request depend on the BI table being queried.

For example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?site_id=3&program_id=1&project_id=2&user_id=10&status=active&date_from=2026-01-01&date_to=2026-06-15&limit=5000

This request includes:

Parameter	Value
`site_id`	`3`
`program_id`	`1`
`project_id`	`2`
`user_id`	`10`
`status`	`active`
`date_from`	`2026-01-01`
`date_to`	`2026-06-15`
`limit`	`5000`

Note

A requested limit may be reduced by FieldOps when a safer maximum is required. Check the query_guard and pagination objects in the response to determine the limit actually applied.

Advanced query syntax¶

FieldOps supports operator-based filtering using this format:

?field=operator:value

The three parts are:

field = operator : value

For example:

status=eq:approved

This means:

Field: status
Operator: eq
Value: approved

The complete request is:

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

Supported operators¶

FieldOps supports the following query operators:

Operator	Meaning	Example
`eq`	Equal to	`status=eq:approved`
`neq`	Not equal to	`status=neq:rejected`
`in`	Match any value in a list	`program_id=in:1,2,3`
`like`	Partial text match	`site_name=like:kibera`
`gt`	Greater than	`field=gt:value`
`lt`	Less than	`field=lt:value`
`between`	Between two values	`visit_date=between:2026-01-01,2026-01-31`

Equal to¶

Use eq to return records where a field equals a specific value.

Syntax:

?field=eq:value

Example: approved visits¶

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

This returns visits whose status is equal to approved.

Example: responses to a specific question¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?question_id=eq:10

This returns visit responses associated with Question ID 10.

Not equal to¶

Use neq to exclude records with a specific value.

Syntax:

?field=neq:value

For example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?status=neq:rejected

This requests visits whose status is not equal to rejected.

Match values in a list¶

Use in when a field can match any value in a comma-separated list.

Syntax:

?field=in:value1,value2,value3

Example: visits in Programme 1 or 2¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?program_id=in:1,2

This returns visits associated with Programme ID 1 or Programme ID 2.

Example: multiple Programmes¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?program_id=in:1,2,3

This returns visits associated with any of the listed Programme IDs.

Partial text matching¶

Use like to search for a partial text value.

Syntax:

?field=like:value

Example: search by Site name¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?site_name=like:kibera

This searches the site_name field for values matching kibera.

This can be useful when the complete Site name is not known.

Greater than¶

Use gt to request records where a field is greater than a specified value.

Syntax:

?field=gt:value

The field and value should be compatible with a greater-than comparison.

Less than¶

Use lt to request records where a field is less than a specified value.

Syntax:

?field=lt:value

The field and value should be compatible with a less-than comparison.

Between two values¶

Use between to request records between two values.

Syntax:

?field=between:start,end

Example: visit date range¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?visit_date=between:2026-01-01,2026-01-31

This requests visits with a visit_date between January 1 and January 31, 2026.

Tip

Use the between operator when filtering a specific date field such as visit_date.

Date range filters¶

FieldOps also supports date range parameters such as:

date_from
date_to

For example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?date_from=2026-01-01&date_to=2026-06-15

This requests records within the specified reporting period.

You can also combine date filters with other filters:

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?program_id=1&project_id=2&date_from=2026-01-01&date_to=2026-06-15

Combining multiple filters¶

Multiple filters can be included in the same request.

Use & to separate query parameters.

For example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?site_id=3&program_id=1&project_id=2&user_id=10&status=active&date_from=2026-01-01&date_to=2026-06-15&limit=5000

This allows a BI client to narrow a request to the specific operational context required for a report.

Combining operator-based filters¶

Operator-based filters can also be combined.

For example:

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

This requests approved visits associated with Programme ID 1.

Another example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?program_id=in:1,2&visit_date=between:2026-01-01,2026-06-30

This requests visits:

In Programme ID 1 or 2
Within the specified date range

Limiting results¶

Use the limit parameter to request a maximum number of records.

For example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?limit=5000

However, the requested limit is not always the final limit applied by FieldOps.

FieldOps evaluates queries and may enforce a safer maximum when necessary.

For example, the response may contain:

{
  "query_guard": {
    "allowed": true,
    "violations": [],
    "warnings": [
      "Raw table query limit forced to 1000"
    ],
    "enforced_limit": 1000
  }
}

In this example:

The request was allowed
FieldOps applied a maximum limit of 1000
The response contains a warning explaining the safeguard

Important

BI clients should check query_guard.enforced_limit and the pagination metadata rather than assuming that the requested limit was applied unchanged.

Safe query handling¶

FieldOps evaluates BI queries before returning data.

A broad or resource-intensive request may result in FieldOps:

Applying a safe result limit
Returning a query warning
Restricting an unsafe query
Serving the request from an optimized BI table
Returning an aggregated dataset
Requiring the client to retrieve additional data through pagination

For example:

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

is a broad request because it does not include filters.

FieldOps may determine that the request can be served more efficiently from an optimized or aggregated BI table.

The response metadata may show:

{
  "meta": {
    "table": "bi_visits",
    "resolved_table": "bi_daily_visit_metrics",
    "aggregated": true
  }
}

This means:

The client requested bi_visits
FieldOps served the request using bi_daily_visit_metrics
The returned result is aggregated

Note

The exact way a query is handled depends on the request. BI clients should inspect the response metadata instead of assuming that every request returns unrestricted raw records.

Query guard¶

The query_guard object describes how FieldOps evaluated a BI request.

For example:

{
  "allowed": true,
  "violations": [],
  "warnings": [
    "Raw table query limit forced to 1000"
  ],
  "enforced_limit": 1000
}

The fields include:

Field	Description
`allowed`	Whether the query was permitted
`violations`	Query rules that prevented or restricted the request
`warnings`	Safeguards or conditions applied to the request
`enforced_limit`	The maximum result limit applied by FieldOps

A query can be successful and still contain warnings.

Tip

When building an automated integration, inspect query_guard.warnings so that the integration can detect when FieldOps has applied a safeguard.

Pagination¶

Use the page parameter to request a specific page.

For example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?page=1

A response may contain:

{
  "pagination": {
    "page": 1,
    "limit": 1000,
    "offset": 0,
    "total": 2500,
    "has_next": true,
    "has_prev": false,
    "total_pages": 3
  }
}

If:

has_next = true

request the next page:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?page=2

Continue until:

has_next = false

Important

BI integrations retrieving complete datasets should follow the pagination metadata rather than assuming that all matching records are returned in the first response.

Using filters with pagination¶

Filters should remain consistent when requesting additional pages.

For example, the first page:

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

The second page:

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

Keep the same filters and change only the page number while retrieving the remaining pages.

Discover fields before querying¶

Before building complex filters, inspect the schema of the BI table.

The schema endpoint follows this structure:

GET /api/bi/schema/{table}

For example:

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

This helps you inspect the fields available in the table before using them in queries.

You can also discover available BI datasets:

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

And inspect a specific dataset:

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

Tip

Use schema and dataset discovery when building a new integration instead of assuming that every BI table contains the same fields.

Query examples¶

Retrieve all permitted visits¶

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

FieldOps may apply safe query controls to a broad request.

Retrieve approved visits¶

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

Retrieve visits in Programme 1 or 2¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?program_id=in:1,2

Search for a Site¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?site_name=like:kibera

Retrieve visits within a date range¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?visit_date=between:2026-01-01,2026-01-31

Retrieve responses to Question 10¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?question_id=eq:10

Apply multiple filters¶

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?site_id=3&program_id=1&project_id=2&user_id=10&status=active&date_from=2026-01-01&date_to=2026-06-15&limit=5000

Querying with cURL¶

Approved visits¶

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/tables/bi_visits?status=eq:approved"

Programme filter¶

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/tables/bi_visits?program_id=in:1,2"

Date range¶

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/tables/bi_visits?visit_date=between:2026-01-01,2026-01-31"

Best practices¶

For efficient and reliable BI queries:

Request only the data required for the analysis
Use Programme, Project, Site, and date filters where appropriate
Use date ranges for larger historical datasets
Use in instead of making repeated requests for several known values
Use pagination when retrieving larger result sets
Inspect query_guard for warnings and enforced limits
Inspect meta to determine whether the response is aggregated
Use schema discovery before building queries against unfamiliar tables
Keep BI Access Tokens secure

What to do next¶

You can now:

Discover the available BI datasets
Inspect the schema of a BI table
Build a filtered BI query
Retrieve the data using your BI Access Token
Follow pagination when additional pages are available

View available datasets

Review the BI API