Farcaster API

API to get a summary overview of Farcaster users and channels.

Server

Base URL

https://api.nanograph.xyz/farcaster

/channel/{channelID}/metrics

GET

Summary:

Get channel metrics

Description:

Retrieves overall metrics for a specific channel, including total casts, replies, likes, recasts, and active users. This data helps channel owners and developers assess the channel's health and activity level.

Parameters

Name	Located in	Description	Required	Schema
channelID	path	The unique identifier of the channel.	Yes	string
date	query	The date for which metrics are requested, in YYYY-MM-DD format. - When timeframe is set to all, the date will be ignored. - For other timeframes, date must be provided. - For weekly or monthly timeframes, date will automatically adjust to the start of the period (Monday for weekly, first of the month for monthly).	No	date
timeframe	query	The timeframe over which to calculate the metrics.	No	string

Responses

Code	Description
200	An object containing the requested channel metrics.
400	The provided channel ID is invalid.
404	The specified channel could not be found.

A successful 200 response returns a JSON object with the following structure:

{
  // The specified date or the start date of the metrics period. 
  // If `timeframe` is `all`, it the date of the first cast in the channel.
  date: string
  // Total casts posted in the channel during the period.
  casts: integer
  // Total replies posted in the channel during the period.
  replies: integer
  // Total likes submitted in the channel during the period.
  likes: integer
  // Total recasts submitted in the channel during the period.
  recasts: integer
  // Number of users who contributed to the channel during the period by sending at least one cast or reply.
  contributors: integer
}

/channel/{channelID}/contributors

GET

Summary:

Get channel contributors

Description:

Retrieves a list of the channel's top contributors, sorted by their contribution amount in descending order.

Parameters

Name	Located in	Description	Required	Schema
channelID	path	The unique identifier of the channel.	Yes	string
date	query	The date for which to retrieve contributors, in YYYY-MM-DD format.	No	date
timeframe	query	The period over which to calculate top contributors.	No	string
page	query	The page number to retrieve, starting from 0.	No	integer
limit	query	The maximum number of contributors to return per page. Defaults to 50, maximum allowed is 100.	No	integer

Responses

Code	Description
200	A list of the channel's top contributors for the specified period.
400	The provided channel ID is invalid.
404	The specified channel could not be found.

A successful 200 response returns a JSON array where each element has the following structure:

{
  // The Farcaster user ID of the contributor.
  fid: string
  // The username of the contributor.
  username: string
  // The number of casts made by this contributor during the period.
  casts: integer
  // The number of replies made by this contributor during the period.
  replies: integer
  // The number of replies received by this contributor during the period.
  receivedReplies: integer
  // The number of likes received by this contributor during the period.
  receivedLikes: integer
  // The number of recasts received by this contributor during the period.
  receivedRecasts: integer
  // The total contribution amount for this contributor during the period.
  // The contribution is calculated from the combined weight of the user's casts, replies, 
  // received replies, received likes, and received recasts in the channel during the period.
  contribution: integer
}

/user/{username}/metrics

GET

Summary:

Get user metrics

Description:

Retrieves metrics for a specific user, including total casts, replies, likes, recasts, and contributions per channel. This data helps channel owners and developers evaluate the user's engagement and activity level.

Parameters

Name	Located in	Description	Required	Schema
username	path	The user's username, typically their first fname.	Yes	string
date	query	The date for which to retrieve metrics, in YYYY-MM-DD format. - When timeframe is set to all, the date will be ignored. - For other timeframes, date must be provided. - For weekly or monthly timeframes, date will automatically adjust to the start of the period (Monday for weekly, first of the month for monthly).	No	date
timeframe	query	The period over which to calculate the metrics.	No	string

Responses

Code	Description
200	A list of the user's metrics across all channels for the specified period.
400	The provided username is invalid.
404	The specified user could not be found.

A successful 200 response returns a JSON array where each element has the following structure:

{
  // The specified date or the start date of the metrics period. 
  // If `timeframe` is `all`, it the date of the user's first cast in the channel.
  date: string
  // The unique identifier of the channel. If it's empty, it means the user's home feed
  channelID: string
  // Total casts made by the user in this channel during the period.
  casts: integer
  // Total replies made by the user in this channel during the period.
  replies: integer
  // Total replies received by the user in this channel during the period.
  receivedReplies: integer
  // Total likes received by the user in this channel during the period.
  receivedLikes: integer
  // Total recasts received by the user in this channel during the period.
  receivedRecasts: integer
  // The user's total contribution amount in this channel during the period.
  // The contribution is calculated from the combined weight of the user's casts, replies, 
  // received replies, received likes, and received recasts in the channel during the period.
  contribution: integer
}