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. chain id
4. date range
5. date
6. account type
7. account source
8. account identifier
9. profile UUID
10. 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 Chain ID

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

It returns all the events on the specific chain id. The chain id should be given as integer.

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.

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.

The are all backed by OpenSearch Aggregations

Example for Bucket Aggregations:

$ 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.

Request

Responses

200

get events matching input query and sorted by id desc