Search for Events

GET 
/search/advanced/events

Introduction

This document explains:

• How one can Search for Events
• How one can Perform Aggregations on Events

Search for Events

This endpoint /search/advanced/events allows you to fetch Events that match specific criteria.

The Search Criteria:

1. id (unique identifier of the Event)
2. type
3. date range
4. date
5. account type
6. account source
7. account identifier
8. profile UUID
9. custom query

The endpoint

Example:

$ curl -G -X GET 'https://api.talentprotocol.com/search/advanced/events' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ey...WA' \
-H 'X-API-KEY: c2a...ec8' \
--data-urlencode 'query={"type":"basename_created"}' \
--data-urlencode 'sort={"id": { "order": "desc" }	}' \
--data-urlencode 'page=1' \
--data-urlencode 'per_page=3'

Example response

{
  "events": [
    {
      "id": "abcdef1234...",
      "type": "basename_created",
      ...
    },
    ...
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 400,
    "total": 10000,
    "total_for_page": 25,
    "point_in_time_id": null,
    "search_after": null
  }
}

Above, you can see how we sort and how we paginate.

Note: The query parameters need to be URL encoded.

Important: Read about Pagination in the documentation for the endpoint /search/advanced/profiles. It works exactly the same.

Search Cases

Search by Id

{
  "query": {
    "id": "0123456789abcde"
  },
  "sort": {
    "id": {
      "order": "asc"
    }
  },
  "page": 1,
  "per_page": 25
}

This will search for the event matching the given id. Please, note that this should always return a single item Array in the result.

Search by Type

{
  "query": {
    "type": "basename_created"
  },
  "sort": {
    "id": {
      "order": "asc"
    }
  },
  "page": 1,
  "per_page": 25
}

This returns all the events that are of the specific type.

Search by Date Range

{
  "query": {
    "dateRange": {
      "gte": "20250701",
      "lte": "20250801",
    }
  },
  "sort": {
    "id": {
      "order": "asc"
    }
  },
  "page": 1,
  "per_page": 25
}

This returns all the events within the specific date range.

The gte and lte are mandatory. They need to be formatted as in the example, i.e. "CCYYMMDD".

Search by Date

{
  "query": {
    "date": "20250705"
  },
  "sort": {
    "id": {
      "order": "asc"
    }
  },
  "page": 1,
  "per_page": 25
}

This returns the events that occurred on the particular date given. The date needs to be in the format CCYYMMDD.

Search by Account Type

{
  "query": {
    "account": {
      "type": "OnchainAccount"
    }
  },
  "sort": {
    "id": {
      "order": "asc"
    }
  },
  "page": 1,
  "per_page": 25
}

This returns all the events generated by accounts of type OnchainAccount.

Valid values are:

• OnchainAccount.
• AuthProviderAccount.

Search by Account Source

{
  "query": {
    "account": {
      "source": "github"
    }
  },
  "sort": {
    "id": {
      "order": "asc"
    }
  },
  "page": 1,
  "per_page": 25
}

This returns all the events generated by accounts of the source given.

The valid values for source are:

• farcaster
• github
• lens
• linkedin
• self
• talent_protocol
• wallet
• worldcoin
• x_twitter

Search by Account Identifier

{
  "query": {
    "account": {
      "identifier": "012345678abcde"
    }
  },
  "sort": {
    "id": {
      "order": "asc"
    }
  },
  "page": 1,
  "per_page": 25
}

This returns all the events generated by the particular account identifier.

Search with Profile UUID

{
  "query": {
    "profileUUID": "012345678abcde"
  },
  "sort": {
    "id": {
      "order": "asc"
    }
  },
  "page": 1,
  "per_page": 25
}

It locates all the events matching the profile UUID given.

Search With Custom Query

Important This feature is only available to paying API keys.

It allows the client application to use the OpenSearch Query DSL to search for events.

This is an example request:

{
  "query": {
    "customQuery": {
      "bool": {
        "must": [
          {
            "nested": {
              "path": "data",
              "query": {
                 "term": {
                    "data.basename.keyword": {
                      "value": "panos.base.eth"
                    }
                 }
              }
            }
          }
        ]
      }
    }
  },
  "sort": {
    "score": {
      "order": "desc"
    }
  },
  "page": 1,
  "per_page": 25
}

This example, returns all the events that have data.basename value equal to panos.base.eth.

Fields for Custom Query

If you want to know the fields that can be used for custom query, you can issue the following request:

$ curl -v -X GET /search/advanced/metadata/fields/events/default \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: <paying-api-key>

It will return a JSON response like the following:

[
  {
    "name": "id",
    "label": "ID",
    "inputType": "text"
  },
  {
    ...
  }
  ...
]

The returned array defines the fields that can be used to query using "customQuery".

Each object describes a field with the following properties:

• name: This is the name of the field. This is what it should be used in the customQuery.
• label: This is a descriptive label that allows you to expose on your UI to build a query builder.
• inputType: This is what is type of the value that can be accepted for the particular field. It can be one of text, number, datetime-local.
• valueEditorType: This is what the UI element to give a value could be. It can be one of: text, select, multi-select checkbox.
• values: This is a list of values with the candidate values one can set to search for.

The name is the most important information here. Because this is the one you will use in the customQuery object. The other properties are only useful if you want to build your own query builder UI.

Note that the schema of each object is based on the React Query Builder component.

Pagination

For pagination read the corresponding section in the documentation of the endpoint /search/advanced/profiles.

Caching

This endpoint returns cached data for free customers. Paying customers get up-to-date data.

Don't Return Matching Documents

Using the query parameter returnItems with value false, you can get statistics and aggregations without getting back the documents that match your filter query.

You can find such an example below, in the list of Examples.

Perform Aggregations On Events

Important! This feature is only available to paying customers.

There are different types of aggregations that one can perform on Events.

• Metric Aggregations: Calculate metrics such as sum, min, max, avg on numeric fields.
• Bucket Aggregations: Sort query results into groups based on some criteria.
• Pipeline Aggregations. Chain together multiple aggregations by using the output of one aggregation as the input for another

They are all backed by OpenSearch Aggregations

Metric Aggregations

Examples to be provided as we add more event types in our database. Current event types do not support any metric aggregations because they don't have a metric to aggregate on.

Bucket Aggregations

Examples of Bucket Aggregations:

Example: Histogram of Basenames Created

$ curl -G -X GET 'https://api.talentprotocol.com/search/advanced/events' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ey...WA' \
-H 'X-API-KEY: c2a...ec8' \
--data-urlencode 'query={"type":"basename_created"}' \
--data-urlencode 'aggregations={"number_of_base_names_created":{"date_histogram":{"field": "date", "interval": "day"}}}'

The above query

• searches for all the Events that are of type basename_created.
• It also builds a histogram for the dates that are involved in the particular events. i.e. it counts the events per date.

Example: Histogram of Smart Contracts Deployed And Average Smart Contracts Deployed Per Date

$ curl -G -X GET 'https://api.talentprotocol.com/search/advanced/events' \
-H 'Accept: application/json' \
-H 'X-API-KEY: 959...c372' \
--data-urlencode 'query={"type":"smart_contract_deployed"}' \
--data-urlencode 'aggregations={
    "number_of_smart_contracts_deployed_per_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "day"
      }
    },
    "average_deployments_per_day": {
      "avg_bucket": {
        "buckets_path": "number_of_smart_contracts_deployed_per_date._count"
      }
    }
  }'

Example: Histogram of Smart Contracts Deployed And Stats on Smart Contracts Deployed Per Date

$ curl -G -X GET 'https://api.talentprotocol.com/search/advanced/events' \
-H 'Accept: application/json' \
-H 'X-API-KEY: 959...572' \
--data-urlencode 'query={"type":"smart_contract_deployed"}' \
--data-urlencode 'aggregations={
    "number_of_smart_contracts_deployed_per_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "day"
      }
    },
    "stats_for_deployed_smart_contracts": {
      "stats_bucket": {
        "buckets_path": "number_of_smart_contracts_deployed_per_date._count"
      }
    }
  }'

Example: Don't Send Query - Aggregate on All Documents

When you don't send a query query parameter, then you don't filter documents and all documents are returned and used for aggregations.

$ curl -G -X GET 'https://api.talentprotocol.com/search/advanced/events' \
-H 'Accept: application/json' \
-H 'X-API-KEY: 959...372' \
--data-urlencode 'aggregations={
    "number_of_smart_contracts_deployed_per_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "day"
      }
    },
    "average_deployments_per_day": {
      "avg_bucket": {
        "buckets_path": "number_of_smart_contracts_deployed_per_date._count"
      }
    }
  }'

Example: Don't Return Matching Documents - Only Aggregations

$ curl -G -X GET 'https://api.talentprotocol.com/search/advanced/events' \
-H 'Accept: application/json' \
-H 'X-API-KEY: 959...c372' \
--data-urlencode 'query={"type":"smart_contract_deployed"}' \
--data-urlencode 'returnItems=false' \
--data-urlencode 'aggregations={
    "number_of_smart_contracts_deployed_per_date": {
      "date_histogram": {
        "field": "date",
        "calendar_interval": "day"
      }
    },
    "average_deployments_per_day": {
      "avg_bucket": {
        "buckets_path": "number_of_smart_contracts_deployed_per_date._count"
      }
    }
  }'

This query returns only the aggregations without returning the matching events.

Request

Responses

200

get events matching input query and sorted by id desc