# pub.chive.metrics.getTrending

> Published by [chive.pub](https://lexicon.garden/identity/did:plc:7natp5xae72bddaqlkef2t4e)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:7natp5xae72bddaqlkef2t4e/pub.chive.metrics.getTrending)
- [Documentation](https://lexicon.garden/lexicon/did:plc:7natp5xae72bddaqlkef2t4e/pub.chive.metrics.getTrending/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:7natp5xae72bddaqlkef2t4e/pub.chive.metrics.getTrending/examples)

## Definitions

### `pub.chive.metrics.getTrending`

**Type**: `query`

Get trending eprints based on view counts within a time window

#### Parameters

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `limit` | `integer` | No | Maximum number of results to return |
| `cursor` | `string` | No | Pagination cursor |
| `window` | `string` | No | Time window for trending calculation |
| `fieldUris` | `array` | No | Optional field URIs to flag matching eprints as in-field |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cursor` | `string` | No | Cursor for next page |
| `window` | `string` | Yes | Time window used |
| `hasMore` | `boolean` | Yes | Whether more results are available |
| `trending` | `array` | Yes |  |

### `pub.chive.metrics.getTrending#fieldRef`

**Type**: `object`

Reference to a knowledge graph field node

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | No | Field ID |
| `uri` | `string` (at-uri) | Yes | AT-URI of the field node |
| `label` | `string` | Yes | Display label |
| `parentUri` | `string` (at-uri) | No | Parent field URI |

### `pub.chive.metrics.getTrending#authorRef`

**Type**: `object`

Reference to an author with optional ATProto identity

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `did` | `string` (did) | No | Author DID (if linked to ATProto identity) |
| `name` | `string` | Yes | Display name |
| `email` | `string` | No | Contact email |
| `orcid` | `string` | No | ORCID identifier |
| `order` | `integer` | Yes | Author order position |
| `handle` | `string` | No | ATProto handle (if resolved) |
| `avatarUrl` | `string` | No | Avatar URL (if available) |
| `affiliations` | `array` | Yes |  |
| `contributions` | `array` | Yes |  |
| `isHighlighted` | `boolean` | No | Whether to highlight this author |
| `isCorrespondingAuthor` | `boolean` | No | Whether this is the corresponding author |

### `pub.chive.metrics.getTrending#sourceInfo`

**Type**: `object`

PDS source information for data transparency

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `stale` | `boolean` | Yes | Whether the indexed data may be stale |
| `blobUrl` | `string` | No | URL to fetch associated blob |
| `recordUrl` | `string` | Yes | Direct URL to fetch the record |
| `pdsEndpoint` | `string` | Yes | URL of the source PDS |
| `lastVerifiedAt` | `string` (datetime) | Yes | When the record was last verified |

### `pub.chive.metrics.getTrending#contribution`

**Type**: `object`

CRediT contribution role

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `degree` | `string` | No | Degree of contribution (lead, supporting, equal) |
| `typeId` | `string` | Yes | Contribution type slug |
| `typeUri` | `string` (at-uri) | Yes | AT-URI of the contribution type node |
| `typeLabel` | `string` | Yes | Human-readable contribution label |

### `pub.chive.metrics.getTrending#eprintMetrics`

**Type**: `object`

Current metrics for the eprint

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `views` | `integer` | Yes | Total view count |
| `downloads` | `integer` | Yes | Total download count |
| `endorsements` | `integer` | No | Endorsement count |

### `pub.chive.metrics.getTrending#trendingEntry`

**Type**: `object`

A trending eprint entry with full metadata

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cid` | `string` (cid) | Yes | CID of the eprint record |
| `uri` | `string` (at-uri) | Yes | AT-URI of the eprint |
| `rank` | `integer` | Yes | Position in trending list |
| `title` | `string` | Yes | Eprint title |
| `fields` | `array` | No | Knowledge graph field classifications |
| `source` | `ref` → `#sourceInfo` | Yes | PDS source information for transparency |
| `authors` | `array` | Yes |  |
| `license` | `string` | Yes | License identifier |
| `metrics` | `ref` → `#eprintMetrics` | No | Current metrics snapshot |
| `abstract` | `array` | Yes | Rich abstract with text, formatting, and entity references |
| `paperDid` | `string` (did) | No | DID of the paper identity (if using paper-centric model) |
| `velocity` | `integer` | No | Rate of view increase (optional) |
| `createdAt` | `string` (datetime) | Yes | Original creation timestamp |
| `indexedAt` | `string` (datetime) | Yes | When Chive indexed this record |
| `submittedBy` | `string` (did) | Yes | DID of the submitter |
| `inUserFields` | `boolean` | No | Whether this eprint matches the requested fieldUris |
| `viewsInWindow` | `integer` | Yes | Views within the trending window |

## Raw Schema

```json
{
  "id": "pub.chive.metrics.getTrending",
  "defs": {
    "main": {
      "type": "query",
      "errors": [],
      "output": {
        "schema": {
          "type": "object",
          "required": [
            "trending",
            "window",
            "hasMore"
          ],
          "properties": {
            "cursor": {
              "type": "string",
              "description": "Cursor for next page"
            },
            "window": {
              "enum": [
                "24h",
                "7d",
                "30d"
              ],
              "type": "string",
              "description": "Time window used"
            },
            "hasMore": {
              "type": "boolean",
              "description": "Whether more results are available"
            },
            "trending": {
              "type": "array",
              "items": {
                "ref": "#trendingEntry",
                "type": "ref"
              }
            }
          }
        },
        "encoding": "application/json"
      },
      "parameters": {
        "type": "params",
        "properties": {
          "limit": {
            "type": "integer",
            "default": 20,
            "maximum": 100,
            "minimum": 1,
            "description": "Maximum number of results to return"
          },
          "cursor": {
            "type": "string",
            "description": "Pagination cursor"
          },
          "window": {
            "enum": [
              "24h",
              "7d",
              "30d"
            ],
            "type": "string",
            "default": "7d",
            "description": "Time window for trending calculation"
          },
          "fieldUris": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "at-uri"
            },
            "maxLength": 50,
            "description": "Optional field URIs to flag matching eprints as in-field"
          }
        }
      },
      "description": "Get trending eprints based on view counts within a time window"
    },
    "fieldRef": {
      "type": "object",
      "required": [
        "uri",
        "label"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Field ID"
        },
        "uri": {
          "type": "string",
          "format": "at-uri",
          "description": "AT-URI of the field node"
        },
        "label": {
          "type": "string",
          "description": "Display label"
        },
        "parentUri": {
          "type": "string",
          "format": "at-uri",
          "description": "Parent field URI"
        }
      },
      "description": "Reference to a knowledge graph field node"
    },
    "authorRef": {
      "type": "object",
      "required": [
        "name",
        "order",
        "affiliations",
        "contributions"
      ],
      "properties": {
        "did": {
          "type": "string",
          "format": "did",
          "description": "Author DID (if linked to ATProto identity)"
        },
        "name": {
          "type": "string",
          "description": "Display name"
        },
        "email": {
          "type": "string",
          "description": "Contact email"
        },
        "orcid": {
          "type": "string",
          "description": "ORCID identifier"
        },
        "order": {
          "type": "integer",
          "minimum": 1,
          "description": "Author order position"
        },
        "handle": {
          "type": "string",
          "description": "ATProto handle (if resolved)"
        },
        "avatarUrl": {
          "type": "string",
          "description": "Avatar URL (if available)"
        },
        "affiliations": {
          "type": "array",
          "items": {
            "ref": "pub.chive.defs#affiliation",
            "type": "ref"
          }
        },
        "contributions": {
          "type": "array",
          "items": {
            "ref": "#contribution",
            "type": "ref"
          }
        },
        "isHighlighted": {
          "type": "boolean",
          "description": "Whether to highlight this author"
        },
        "isCorrespondingAuthor": {
          "type": "boolean",
          "description": "Whether this is the corresponding author"
        }
      },
      "description": "Reference to an author with optional ATProto identity"
    },
    "sourceInfo": {
      "type": "object",
      "required": [
        "pdsEndpoint",
        "recordUrl",
        "lastVerifiedAt",
        "stale"
      ],
      "properties": {
        "stale": {
          "type": "boolean",
          "description": "Whether the indexed data may be stale"
        },
        "blobUrl": {
          "type": "string",
          "description": "URL to fetch associated blob"
        },
        "recordUrl": {
          "type": "string",
          "description": "Direct URL to fetch the record"
        },
        "pdsEndpoint": {
          "type": "string",
          "description": "URL of the source PDS"
        },
        "lastVerifiedAt": {
          "type": "string",
          "format": "datetime",
          "description": "When the record was last verified"
        }
      },
      "description": "PDS source information for data transparency"
    },
    "contribution": {
      "type": "object",
      "required": [
        "typeUri",
        "typeId",
        "typeLabel"
      ],
      "properties": {
        "degree": {
          "type": "string",
          "description": "Degree of contribution (lead, supporting, equal)"
        },
        "typeId": {
          "type": "string",
          "description": "Contribution type slug"
        },
        "typeUri": {
          "type": "string",
          "format": "at-uri",
          "description": "AT-URI of the contribution type node"
        },
        "typeLabel": {
          "type": "string",
          "description": "Human-readable contribution label"
        }
      },
      "description": "CRediT contribution role"
    },
    "eprintMetrics": {
      "type": "object",
      "required": [
        "views",
        "downloads"
      ],
      "properties": {
        "views": {
          "type": "integer",
          "minimum": 0,
          "description": "Total view count"
        },
        "downloads": {
          "type": "integer",
          "minimum": 0,
          "description": "Total download count"
        },
        "endorsements": {
          "type": "integer",
          "minimum": 0,
          "description": "Endorsement count"
        }
      },
      "description": "Current metrics for the eprint"
    },
    "trendingEntry": {
      "type": "object",
      "required": [
        "uri",
        "cid",
        "title",
        "abstract",
        "authors",
        "submittedBy",
        "license",
        "createdAt",
        "indexedAt",
        "source",
        "viewsInWindow",
        "rank"
      ],
      "properties": {
        "cid": {
          "type": "string",
          "format": "cid",
          "description": "CID of the eprint record"
        },
        "uri": {
          "type": "string",
          "format": "at-uri",
          "description": "AT-URI of the eprint"
        },
        "rank": {
          "type": "integer",
          "minimum": 1,
          "description": "Position in trending list"
        },
        "title": {
          "type": "string",
          "description": "Eprint title"
        },
        "fields": {
          "type": "array",
          "items": {
            "ref": "#fieldRef",
            "type": "ref"
          },
          "description": "Knowledge graph field classifications"
        },
        "source": {
          "ref": "#sourceInfo",
          "type": "ref",
          "description": "PDS source information for transparency"
        },
        "authors": {
          "type": "array",
          "items": {
            "ref": "#authorRef",
            "type": "ref"
          }
        },
        "license": {
          "type": "string",
          "description": "License identifier"
        },
        "metrics": {
          "ref": "#eprintMetrics",
          "type": "ref",
          "description": "Current metrics snapshot"
        },
        "abstract": {
          "type": "array",
          "items": {
            "refs": [
              "pub.chive.richtext.defs#textItem",
              "pub.chive.richtext.defs#nodeRefItem",
              "pub.chive.richtext.defs#wikidataRefItem",
              "pub.chive.richtext.defs#fieldRefItem",
              "pub.chive.richtext.defs#facetRefItem",
              "pub.chive.richtext.defs#eprintRefItem",
              "pub.chive.richtext.defs#annotationRefItem",
              "pub.chive.richtext.defs#authorRefItem",
              "pub.chive.richtext.defs#mentionItem",
              "pub.chive.richtext.defs#linkItem",
              "pub.chive.richtext.defs#tagItem",
              "pub.chive.richtext.defs#latexItem",
              "pub.chive.richtext.defs#codeBlockItem",
              "pub.chive.richtext.defs#headingItem",
              "pub.chive.richtext.defs#listItem",
              "pub.chive.richtext.defs#blockquoteItem"
            ],
            "type": "union"
          },
          "maxLength": 500,
          "description": "Rich abstract with text, formatting, and entity references"
        },
        "paperDid": {
          "type": "string",
          "format": "did",
          "description": "DID of the paper identity (if using paper-centric model)"
        },
        "velocity": {
          "type": "integer",
          "description": "Rate of view increase (optional)"
        },
        "createdAt": {
          "type": "string",
          "format": "datetime",
          "description": "Original creation timestamp"
        },
        "indexedAt": {
          "type": "string",
          "format": "datetime",
          "description": "When Chive indexed this record"
        },
        "submittedBy": {
          "type": "string",
          "format": "did",
          "description": "DID of the submitter"
        },
        "inUserFields": {
          "type": "boolean",
          "description": "Whether this eprint matches the requested fieldUris"
        },
        "viewsInWindow": {
          "type": "integer",
          "minimum": 0,
          "description": "Views within the trending window"
        }
      },
      "description": "A trending eprint entry with full metadata"
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "revision": 2
}
```