> ## Documentation Index > Fetch the complete documentation index at: https://docs.serval.com/llms.txt > Use this file to discover all available pages before exploring further. # List Knowledge Citations > List actual stored knowledge citations for an authorized team and answer date range. Each record represents one answer-turn/article pair; chunkCount counts distinct cited chunks. The date range must not exceed 31 days; split longer history into adjacent windows. startTime is inclusive and endTime exclusive, using the first completed, non-deleted assistant message in the turn. Deleted and trashed tickets, deleted and unfinished assistant messages are excluded. Simulations are excluded unless includeSimulations is true. Results use keyset pagination ordered by answeredAt, ticketId, answerTurnId and articleId. Keep filters unchanged when following nextPageToken; results reflect current data rather than a snapshot. articleId is the stored knowledge item ID. For Serval knowledge documents, use Get Knowledge Document to retrieve the title and knowledge base, then List Knowledge Bases for source information. ## Authentication and permissions > **Token requirements:** **Organization-scoped API key** or **Team-scoped API key**. > > Send a bearer access token for one of these identities. The permissions and resource restrictions below also apply. | Credential | Access requirements | | - | - | | Organization-scoped API key | `tickets:read` | | Team-scoped API key | `tickets:read` | | User-based token (OAuth) | Unsupported | Permissions joined by **+** are all required; **or** separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Team keys must allow every team checked by the request. OAuth access depends on the user’s roles and resource access. ## OpenAPI ````yaml /sections/api-reference/openapi-spec-v2.yaml get /v2/knowledge-citations openapi: 3.1.0 info: title: Serval Public API description: Serval Public API contact: name: Serval url: https://serval.com email: support@serval.com license: name: Serval License url: https://serval.com/license version: 2.0.0 servers: - url: https://public.api.serval.com security: - BearerAuth: [] tags: - name: Access Membership API - name: Access Policy API - name: Access Policy Approval Procedure API - name: Access Profile API - name: Access Relationship API - name: Access Request API - name: Agent API - name: Analytics API - name: App Instance API - name: App Resource API - name: App Resource Role API - name: Approval Delegation API - name: Approval Procedure API - name: Approval Request API - name: Assignment Rules API - name: Audit Log API - name: Billing API - name: Browser API - name: Campaign API - name: Change Blackout API - name: Change Model API - name: Connected Channels API - name: Custom Field API - name: Custom Role API - name: Custom Service API - name: Dashboards API - name: Email Intake API - name: Entity API - name: Entity Field Mapping API - name: Entity Ingestion Config API - name: Entity Type API - name: Folder API - name: Forms API - name: Group API - name: Guidance API - name: Help Agent API - name: Improvement Request API - name: Journey API - name: Knowledge API - name: Knowledge Base API - name: One-Time Window API - name: Package API - name: Report API - name: Review API - name: Roles API - name: SLA API - name: Schedule API - name: Tag API - name: Team API - name: Team Group API - name: Team SDLC Settings API - name: Team User API - name: Ticket API - name: Ticket Import API - name: Topic API - name: User API - name: User Relationship API - name: Widgets API - name: Worker API - name: Workflow API - name: Workflow Approval Procedure API - name: Workflow Run API paths: /v2/knowledge-citations: get: tags: - Ticket API summary: List Knowledge Citations description: >- List actual stored knowledge citations for an authorized team and answer date range. Each record represents one answer-turn/article pair; chunkCount counts distinct cited chunks. The date range must not exceed 31 days; split longer history into adjacent windows. startTime is inclusive and endTime exclusive, using the first completed, non-deleted assistant message in the turn. Deleted and trashed tickets, deleted and unfinished assistant messages are excluded. Simulations are excluded unless includeSimulations is true. Results use keyset pagination ordered by answeredAt, ticketId, answerTurnId and articleId. Keep filters unchanged when following nextPageToken; results reflect current data rather than a snapshot. articleId is the stored knowledge item ID. For Serval knowledge documents, use Get Knowledge Document to retrieve the title and knowledge base, then List Knowledge Bases for source information. operationId: svrelay.publicv2.PublicAPIServiceV2.ListKnowledgeCitations parameters: - name: teamId in: query required: true schema: type: string title: team_id - name: startTime in: query required: true schema: type: string examples: - '2023-01-15T01:30:15.01Z' - '2024-12-25T12:00:00Z' format: date-time description: >- A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format. - name: endTime in: query required: true schema: type: string examples: - '2023-01-15T01:30:15.01Z' - '2024-12-25T12:00:00Z' format: date-time description: >- A Timestamp represents a point in time independent of any time zone or local calendar, encoded as a count of seconds and fractions of seconds at nanosecond resolution. The count is relative to an epoch at UTC midnight on January 1, 1970, in the proleptic Gregorian calendar which extends the Gregorian calendar backwards to year one. All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap second table is needed for interpretation, using a [24-hour linear smear](https://developers.google.com/time/smear). The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By restricting to that range, we ensure that we can convert to and from [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. # Examples Example 1: Compute Timestamp from POSIX `time()`. Timestamp timestamp; timestamp.set_seconds(time(NULL)); timestamp.set_nanos(0); Example 2: Compute Timestamp from POSIX `gettimeofday()`. struct timeval tv; gettimeofday(&tv, NULL); Timestamp timestamp; timestamp.set_seconds(tv.tv_sec); timestamp.set_nanos(tv.tv_usec * 1000); Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. FILETIME ft; GetSystemTimeAsFileTime(&ft); UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. Timestamp timestamp; timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. long millis = System.currentTimeMillis(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) .setNanos((int) ((millis % 1000) * 1000000)).build(); Example 5: Compute Timestamp from Java `Instant.now()`. Instant now = Instant.now(); Timestamp timestamp = Timestamp.newBuilder().setSeconds(now.getEpochSecond()) .setNanos(now.getNano()).build(); Example 6: Compute Timestamp from current time in Python. timestamp = Timestamp() timestamp.GetCurrentTime() # JSON Mapping In JSON format, the Timestamp type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where {year} is always expressed using four digits while {month}, {day}, {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone is required. A proto3 JSON serializer should always use UTC (as indicated by "Z") when printing the Timestamp type and a proto3 JSON parser should be able to accept both UTC and other timezones (as indicated by an offset). For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past 01:30 UTC on January 15, 2017. In JavaScript, one can convert a Date object to this format using the standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) method. In Python, a standard `datetime.datetime` object can be converted to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() ) to obtain a formatter capable of generating timestamps in this format. - name: includeSimulations in: query schema: type: boolean title: include_simulations - name: pageSize in: query schema: type: integer title: page_size format: int32 description: Defaults to 100; maximum 1000. - name: pageToken in: query schema: type: string title: page_token responses: '200': description: Success content: application/json: schema: $ref: >- #/components/schemas/svhelp.publicapi.ListKnowledgeCitationsResponse security: - BearerAuth: [] components: schemas: svhelp.publicapi.ListKnowledgeCitationsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/svhelp.pubapimodels.KnowledgeCitation' title: data x-stainless-terraform-configurability: optional nextPageToken: type: - string - 'null' title: next_page_token x-stainless-terraform-configurability: optional title: ListKnowledgeCitationsResponse additionalProperties: false svhelp.pubapimodels.KnowledgeCitation: type: object properties: ticketId: type: string title: ticket_id x-stainless-terraform-configurability: optional answerTurnId: type: string title: answer_turn_id x-stainless-terraform-configurability: optional articleId: type: string title: article_id description: >- The stored knowledge item ID; native documents resolve via Get Knowledge Document. x-stainless-terraform-configurability: optional answeredAt: $ref: '#/components/schemas/google.protobuf.Timestamp' title: answered_at x-stainless-terraform-configurability: optional chunkCount: type: integer title: chunk_count format: int32 x-stainless-terraform-configurability: optional isSimulation: type: boolean title: is_simulation x-stainless-terraform-configurability: computed_optional title: KnowledgeCitation additionalProperties: false description: >- One stored answer-turn/article pair, even when several chunks were cited. google.protobuf.Timestamp: type: string examples: - '2025-01-15T01:30:15.000Z' - '2025-06-01T00:00:00.000Z' format: date-time description: A timestamp in RFC 3339 format (e.g., "2025-01-15T01:30:15Z"). securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.