Skip to main content
POST
/
v0
/
reporting
/
query
curl --request POST \
  --url https://api.avidoai.com/v0/reporting/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-application-id: <api-key>' \
  --data '
{
  "datasource": "task"
}
'
{
  "data": {
    "datasource": "task",
    "columns": [
      {
        "id": "id",
        "name": "Task ID",
        "type": "string"
      },
      {
        "id": "orgId",
        "name": "Organization ID",
        "type": "string"
      },
      {
        "id": "title",
        "name": "Title",
        "type": "string"
      },
      {
        "id": "type",
        "name": "Task Type",
        "type": "string"
      },
      {
        "id": "topicId",
        "name": "Topic",
        "type": "string"
      },
      {
        "id": "createdAt",
        "name": "Created Date",
        "type": "date"
      }
    ],
    "results": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "orgId": "org_123456",
        "title": "Example Task",
        "type": "STATIC",
        "topicId": {
          "id": "topic-uuid-123",
          "name": "Authentication"
        },
        "createdAt": "2024-01-05T12:34:56.789Z"
      }
    ],
    "visualization": {
      "compatibleCharts": [
        "table"
      ],
      "recommendedChart": "table",
      "fieldMapping": {
        "measures": []
      }
    }
  },
  "pagination": {
    "skip": 0,
    "limit": 25,
    "total": 1,
    "totalPages": 1
  }
}

Authorizations

​
x-api-key
string
header
required

Your unique Avido API key

​
x-application-id
string
header
required

Your unique Avido Application ID

Body

application/json

Request body for querying reporting data

​
datasource
enum<string>
required

Datasource to query

Available options:
task,
test,
eval,
topic,
tag,
human_annotation
Example:

"task"

​
timezone
string
required

IANA timezone identifier for date filter resolution (e.g., 'America/New_York', 'Europe/London', 'UTC')

Example:

"America/New_York"

​
skip
integer
default:0

Number of items to skip before starting to collect the result set.

Required range: 0 <= x <= 9007199254740991
Example:

0

​
limit
integer

Number of items to include in the result set.

Required range: 1 <= x <= 100
Example:

25

​
filters
(ReportingQueryStringFilter · object | ReportingQueryNumberFilter · object | ReportingQueryBooleanFilter · object | ReportingQueryDateFilter · object)[]

Optional filters to apply to the query. Each filter must specify a type (string/number/boolean/date) that matches the column type.

Filter for string columns using eq/neq operators

Example:
[
  {
    "type": "string",
    "column": "type",
    "operator": "eq",
    "value": ["STATIC"]
  }
]
​
groupBy
(ReportingQueryGroupByBase · object | ReportingQueryGroupByDate · object)[]

Optional group by clauses for aggregating results. For date columns, dateTrunc is required.

Group by specification for non-date columns

Example:
[
  { "column": "type", "type": "string" },
  {
    "column": "createdAt",
    "type": "date",
    "dateTrunc": "month"
  }
]
​
measurements
Measurement · object[]

Optional measurements/aggregations to compute when using groupBy. Defaults to count if not specified. Use avg/sum/min/max for numeric or boolean columns.

Example:
[
  { "type": "count" },
  { "type": "avg", "column": "score" }
]
​
orderBy
ReportingQueryOrderBy · object[]

Optional ordering specification. If not specified, defaults to ordering by all groupBy columns (with createdAt priority) then measurements. For non-groupBy queries, defaults to createdAt DESC, id DESC.

Example:
[
  {
    "column": "createdAt",
    "direction": "desc"
  },
  { "column": "count", "direction": "asc" }
]
​
includeArchived
boolean

When true, includes archived entities (tasks, topics, tags) in the query results. Defaults to false, which filters out archived data.

Example:

false

Response

Successfully queried reporting data

Successful response from reporting query with column metadata and visualization hints

​
data
object
required
​
pagination
PaginationResponse · object
required

Pagination metadata returned in a paginated response.