Data Fetching

The execute function is an alias for refresh that works in exactly the same way but is more semantic for cases when the fetch is not immediate .

Clear

If you want to clear the data provided, for whatever reason, without needing to know the specific key to pass to clearNuxtData , you can use the clear function provided by the composables.

<script setup lang="ts">
const { 
data
, 
clear
 } = await 
useFetch
('/api/users')
const 
route
 = 
useRoute
()
watch
(() => 
route
.
path
, (
path
) => {
  if (
path
 === '/') {
    
clear
()
</script>

Watch

To re-run your fetching function each time other reactive values in your application change, use the watch option. You can use it for one or multiple watchable elements.

<script setup lang="ts">
const 
id
 = 
ref
(1)
const { 
data
, 
error
, 
refresh
 } = await 
useFetch
('/api/users', {
  /* Changing the id will trigger a refetch */
  
watch
: [
id
],
</script>

Note that watching a reactive value won't change the URL fetched . For example, this will keep fetching the same initial ID of the user because the URL is constructed at the moment the function is invoked.

<script setup lang="ts">
const id = ref(1)
const { data, error, refresh } = await useFetch(`/api/users/${id.value}`, {
  watch: [id],
</script>

If you need to change the URL based on a reactive value, you may want to use a computed URL instead.

When reactive fetch options are provided, they'll be automatically watched and trigger refetches. In some cases, it can be useful to opt-out of this behavior by specifying watch: false .

const id = ref(1)
// Won't automatically refetch when id changes
const { data, execute } = await useFetch('/api/users', {
  query: { id }, // id is watched by default
  watch: false, // disables automatic watching of id
// doesn't trigger refetch
id.value = 2

Computed URL

Sometimes you may need to compute a URL from reactive values, and refresh the data each time these change. Instead of juggling your way around, you can attach each param as a reactive value. Nuxt will automatically use the reactive value and re-fetch each time it changes.

<script setup lang="ts">
const id = ref(null)
const { data, status } = useLazyFetch('/api/user', {
  query: {
    user_id: id,
</script>

In the case of more complex URL construction, you may use a callback as a computed getter that returns the URL string.

Every time a dependency changes, the data will be fetched using the newly constructed URL. Combine this with not-immediate , and you can wait until the reactive element changes before fetching.

<script setup lang="ts">
const id = ref(null)
const { data, status } = useLazyFetch(() => `/api/users/${id.value}`, {
  immediate: false,
const pending = computed(() => status.value === 'pending')
</script>
<template>
    <!-- disable the input while fetching -->
    <input
      v-model="id"
      type="number"
      :disabled="pending"
    <div v-if="status === 'idle'">
      Type a user ID
    </div>
    <div v-else-if="pending">
      Loading ...
    </div>
    <div v-else>
      {{ data }}
    </div>
  </div>
</template>

If you need to force a refresh when other reactive values change, you can also watch other values .

Not immediate

The useFetch composable will start fetching data the moment is invoked. You may prevent this by setting immediate: false , for example, to wait for user interaction.

With that, you will need both the status to handle the fetch lifecycle, and execute to start the data fetch.

<script setup lang="ts">
const { data, error, execute, status } = await useLazyFetch('/api/comments', {
  immediate: false,
</script>
<template>
  <div v-if="status === 'idle'">
    <button @click="execute">
      Get data
    </button>
  </div




    
>
  <div v-else-if="status === 'pending'">
    Loading comments...
  </div>
  <div v-else>
    {{ data }}
  </div>
</template>

For finer control, the status variable can be:

• idle when the fetch hasn't started
• pending when a fetch has started but not yet completed
• error when the fetch fails
• success when the fetch is completed successfully

Passing Headers and Cookies

When we call $fetch in the browser, user headers like cookie will be directly sent to the API.

Normally, during server-side-rendering, due to security considerations, the $fetch wouldn't include the user's browser cookies, nor pass on cookies from the fetch response.

However, when calling useFetch with a relative URL on the server, Nuxt will use useRequestFetch to proxy headers and cookies (with the exception of headers not meant to be forwarded, like host ).

Pass Cookies From Server-side API Calls on SSR Response

If you want to pass on/proxy cookies in the other direction, from an internal request back to the client, you will need to handle this yourself.

import { appendResponseHeader } from 'h3'
import type { H3Event } from 'h3'
export const fetchWithCookie = async (event: H3Event, url: string) => {
  /* Get the response from the server endpoint */
  const res = await $fetch.raw(url)
  /* Get the cookies from the response */
  const cookies = res.headers.getSetCookie()
  /* Attach each cookie to our incoming Request */
  for (const cookie of cookies) {
    appendResponseHeader(event, 'set-cookie', cookie)
  /* Return the data of the response */
  return res._data

<script setup lang="ts">
// This composable will automatically pass cookies to the client
const event = useRequestEvent()
const { data: result } = await useAsyncData(() => fetchWithCookie(event!, '/api/with-cookie'))
onMounted(() => console.log(document.cookie))
</




    
script>

Options API Support

Nuxt provides a way to perform asyncData fetching within the Options API. You must wrap your component definition within defineNuxtComponent for this to work.

<script>
export default defineNuxtComponent({
  /* Use the fetchKey option to provide a unique key */
  fetchKey: 'hello',
  async asyncData () {
    return {
      hello: await $fetch('/api/hello'),
</script>

Serializing Data From Server to Client

When using useAsyncData and useLazyAsyncData to transfer data fetched on server to the client (as well as anything else that utilizes the Nuxt payload ), the payload is serialized with devalue . This allows us to transfer not just basic JSON but also to serialize and revive/deserialize more advanced kinds of data, such as regular expressions, Dates, Map and Set, ref , reactive , shallowRef , shallowReactive and NuxtError - and more.

It is also possible to define your own serializer/deserializer for types that are not supported by Nuxt. You can read more in the useNuxtApp docs.

Serializing Data From API Routes

When fetching data from the server directory, the response is serialized using JSON.stringify . However, since serialization is limited to only JavaScript primitive types, Nuxt does its best to convert the return type of $fetch and useFetch to match the actual value.

Example

export default defineEventHandler(() => {
  return new Date()

<script setup lang="ts">
// Type of `data` is inferred as string even though we returned a Date object
const { data } = await useFetch('/api/foo')
</script>

Custom serializer function

To customize the serialization behavior, you can define a toJSON function on your returned object. If you define a toJSON method, Nuxt will respect the return type of the function and will not try to convert the types.

export default defineEventHandler(() => {
  const data = {
    createdAt: new Date(),
    toJSON () {
      return {
        createdAt: {
          year: this.createdAt.getFullYear(),
          month: this.createdAt.getMonth(),
          day: this.createdAt.getDate(),
  return data

<script setup lang="ts">
// Type of `data` is inferred as
//   createdAt: {
//     year: number
//     month: number
//     day: number
//   }
const { data } = await useFetch('/api/bar')
</script>

Using an alternative serializer

Nuxt does not currently support an alternative serializer to JSON.stringify . However, you can return your payload as a normal string and utilize the toJSON method to maintain type safety.

In the example below, we use superjson as our serializer.

import superjson from 'superjson'
export default defineEventHandler(() => {
  const data = {
    createdAt: new Date(),
    // Workaround the type conversion
    toJSON () {
      return this
  // Serialize the output to string, using superjson
  return superjson.stringify(data) as unknown as typeof data

<script setup lang="ts">
import superjson from 'superjson'
// `date` is inferred as { createdAt: Date } and you can safely use the Date object methods
const { data } = await useFetch('/api/superjson', {
  transform: (value) => {
    return superjson.parse(value as unknown as string)
</script>

Recipes

Consuming SSE (Server-Sent Events) via POST request

When consuming SSE via POST request, you need to handle the connection manually. Here's how you can do it:

// Make a POST request to the SSE endpoint
const response = await $fetch<ReadableStream>('/chats/ask-ai', {
  method: 'POST',
  body: {
    query: 'Hello AI, how are you?',
  responseType: 'stream',
// Create a new ReadableStream from the response with TextDecoderStream to get the data as text
const reader = response.pipeThrough(new TextDecoderStream()).getReader()
// Read the chunk of data as we get it
while (true) {
  const { value, done } = await reader.read()
  if (done) { break }
  console.log('Received:', value)

Making parallel requests

When requests don't rely on each other, you can make them in parallel with Promise.all() to boost performance.

const { data } = await useAsyncData((_nuxtApp, { signal }) => {
  return Promise.all([
    $fetch('/api/comments/', { signal }),
    $fetch('/api/author/12', { signal }),