Welcome to the Frame Analytics API! This API will give you finer grain access to Frame Analytics than the FDK and unlock some unique applications

To get started you will need a Pinata API Key!

​
API Keys

Visit the Pinata API Keys page to generate new keys.

In the ‘New Key’ modal, you can choose if you want the key to be an Admin key and have full access over every endpoint, or scope the keys by selecting which endpoints you want to use. You can also give it a limited number of uses, so be sure to give it a name to keep track of it. Once you have that filled out, click “Generate API Key” and it will show you the pinata_api_key, pinata_api_secret_key, and the JWT. It’s best to click “Copy All” and keep the API key data safe and secure.

Once API keys have been created, you will not be able to see the secret or JWT again

Once you have created your keys you can go ahead and try testing them! Try to paste this into your terminal with your JWT

curl --request GET \
     --url https://api.pinata.cloud/v3/farcaster/users/1 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_PINATA_JWT'

If successful you should see something like this!

200
{
  "data": {
    "fid": 1,
    "custody_address": "0x8773442740c17c9d0f0b87022c722f9a136206ed",
    "recovery_address": "0x00000000fcb080a4d6c39a9354da9eb9bc104cd7",
    "following_count": 2,
    "follower_count": 7945,
    "verifications": ["0x86924c37a93734e8611eb081238928a9d18a63c0"],
    "bio": "A sufficiently decentralized social network. farcaster.xyz",
    "display_name": "Farcaster",
    "pfp_url": "https://i.imgur.com/I2rEbPF.png",
    "username": "farcaster"
  }
}

​
Endpoints Overview

​
/interactions

This endpoint is used for both sending analytics and fetching them for a set of parameters

​
Send Analytics

frame_id
string
required

Can be any name you want to give your frame to reflect in the analytics results

custom_id
string

More granular for specific parts of your frame

frame_data
object
required

An object representing the raw payload of an action frame produced by Farcaster.

{
  "untrustedData": {
    "fid": 2,
    "url": "https://fcpolls.com/polls/1",
    "messageHash": "0xd2b1ddc6c88e865a33cb1a565e0058d757042974",
    "timestamp": 1706243218,
    "network": 1,
    "buttonIndex": 2,
    "inputText": "hello world",
    "castId": {
      "fid": 226,
      "hash": "0xa48dd46161d8e57725f5e26e34ec19c13ff7f3b9"
    }
  },
  "trustedData": {
    "messageBytes": "d2b1ddc6c88e865a33cb1a565e0058d757042974..."
  }
}

​
Get Interactions

start_date

Start date for the analytics results in the format of YYYY-MM-DD HH:MM:SS

end_date

End date for the analytics results in the format of YYYY-MM-DD HH:MM:SS

frame_id

Filters results by a specified frame_id used in the initial post request

button_index

Filters results by the button_index used in the frame payload

url

Filters results by the url of a frame

custom_id

Filters results by a specified custom_id used in the initial post request

​
/interactions/top

Instead of fetching the interactions for a specific frame, get results for all frames with analytics in your Pinata account

​
Get Top Interactions

start_date

Start date for the analytics results in the format of YYYY-MM-DD HH:MM:SS

end_date

End date for the analytics results in the format of YYYY-MM-DD HH:MM:SS

by

Filters results for a specific attribute. The following are available:

  • button_index
  • cast_fid
  • cast_hash
  • frame_id
  • url
Get SignersSend Analytics